Back in 2002, Joel Spolsky wrote The Law of Leaky Abstractions, and it's one of those pieces that's stuck with me ever since I first read it. 23+ years later 💀 and I'm still bringing it up in conversations, and the concept remains just as relevant. But the last time I recommended it to someone, I couldn't help but notice how dated the examples felt ... TCP packets, C string manipulation, ASP.NET DataGrids.
As a fellow Joel, I figured it was my duty to update this for a more modern audience, especially since he stopped blogging back in 2010 (16 years ago 🤯). So here we are.
The Core Idea Still Holds
If you haven't read the original, the gist is simple: all non-trivial abstractions leak. The promise of an abstraction is that you don't need to understand what's underneath ... but inevitably, the underlying complexity seeps through, and when it does, you're stuck debugging something you thought you could ignore.
The real insight isn't just that abstractions leak — it's that understanding how they leak is critical to using them effectively. When things break, you need knowledge of the lower layers to fix them. And if you're building abstractions yourself, projecting forward to understand how they'll leak can save everyone a ton of headaches down the line.
Modern Examples
Here are some contemporary examples of leaky abstractions I've run into, along with the pain they cause and the knowledge you need to work around them:
Serverless Functions
The abstraction: You don't need to think about servers. Just write your function and deploy.
How it leaks: Cold starts, execution time limits, memory constraints, and pricing that scales in unexpected ways. That "infinite scale" promise hits a wall when you discover your function timing out at 15 minutes, or you're paying way more than expected because you didn't understand invocation costs vs duration costs.
What you need to know: Traditional server architectures, statelessness, connection pooling strategies, and how to optimize for short execution times. You end up needing to understand the underlying container lifecycle, warm-up strategies, and regional deployment patterns — all the things you thought you were abstracting away.
ORMs (Object-Relational Mappers)
The abstraction: Work with objects, not SQL. The ORM handles the database for you.
How it leaks: N+1 query problems, lazy vs eager loading confusion, inefficient queries that an ORM generates, transactions that behave differently than you expect, and migrations that break in production.
What you need to know: SQL, database indexes, query execution plans, connection pooling, and transaction isolation levels. When your "simple" query takes 30 seconds, you need to understand what SQL is actually being generated and how the database is executing it. You might even need to drop down to raw SQL for complex queries or bulk operations.
Kubernetes
The abstraction: Deploy your containerized app anywhere. K8s handles orchestration, scaling, and recovery.
How it leaks: Pod scheduling failures, resource limits causing OOMKills, networking issues between services, persistent volume claims not mounting, readiness vs liveness probe confusion, and YAML configuration sprawl that feels more complex than what you're actually deploying.
What you need to know: Container runtimes, Linux namespaces and cgroups, networking (CNI plugins, service meshes), storage systems, and the entire cluster architecture. When a pod won't schedule, you're digging into node selectors, taints, tolerations, and resource quotas — stuff that feels pretty far from "just deploy my app."
React State Management
The abstraction: Just manage component state with hooks. Simple and declarative.
How it leaks: Stale closures, infinite re-render loops, dependency arrays that are hard to reason about, useEffect that fires at unexpected times, and performance issues from unnecessary re-renders.
What you need to know: JavaScript closures, React's reconciliation algorithm, how the virtual DOM works, and when React batches updates. You thought you could just "use state," but now you're deep in the weeds of useCallback, useMemo, and trying to understand why your effect isn't seeing the latest value.
Promises and async/await
The abstraction: Write asynchronous code that looks synchronous. No more callback hell.
How it leaks: Unhandled promise rejections, race conditions, promises that don't run in parallel when you expected them to, await blocking when you didn't want it to, and error handling that's easy to forget.
What you need to know: The event loop, microtasks vs macrotasks, and how promises actually work under the hood. When your "simple" async function is running slower than expected, you realize you're awaiting sequentially when you could parallelize with Promise.all, or you're blocking the event loop with synchronous work.
GraphQL
The abstraction: Request exactly the data you need. No more over-fetching or under-fetching.
How it leaks: The N+1 problem (again, but worse), resolver performance issues, complex caching strategies, and queries that seem simple but hammer your database or downstream APIs with hundreds of requests.
What you need to know: DataLoader patterns, query complexity analysis, how to implement efficient batching, database query optimization, and sometimes you need to understand the entire request waterfall to figure out why your "efficient" GraphQL query is actually making 200 backend calls.
Docker Containers
The abstraction: Package your app with its dependencies. Run anywhere.
How it leaks: Image layer caching confusion, multi-stage builds that don't optimize correctly, networking between containers, volume mounting permissions on different host OSes, and "works on my machine" still happening because of platform-specific builds (looking at you, ARM vs x86).
What you need to know: Linux file systems, process namespaces, overlay filesystems, platform-specific binary compilation, and the difference between CMD and ENTRYPOINT. When your container "just works" locally but fails in production, you're suddenly learning about init systems, signal handling, and PID 1.
AI/LLM APIs
The abstraction: Just send a prompt, get intelligent responses back. The model handles understanding.
How it leaks: Token limits hit you unexpectedly, context window management becomes critical, non-deterministic outputs make testing nearly impossible, rate limits and throttling, hallucinations that you need to detect and handle, and costs that scale faster than you anticipated.
What you need to know: Tokenization (not all characters are equal), prompt engineering techniques, chunking strategies for long documents, how to implement semantic caching, and when you need to fine-tune vs use RAG vs just better prompting. You thought you could just "ask the AI," but now you're managing conversation history, implementing retrieval strategies, and trying to make outputs deterministic enough to build reliable features on top of.
The Takeaway
The pattern is always the same: the abstraction promises simplicity, but when you hit the edges, you need deep knowledge of what's beneath it. This isn't an argument against abstractions — they're essential for building complex systems. But it's a reminder that good abstractions acknowledge their limitations.
If you're designing an abstraction (an API, a framework, a platform), spend time thinking about how it will leak. What will developers need to know when things go wrong? How can you make those failure modes discoverable? What escape hatches should you provide for when the abstraction doesn't fit?
And if you're using an abstraction, invest time understanding the layer below. You don't need to be an expert, but having a mental model of how things actually work will save you hours (or days) when you inevitably hit a leak.
The Law of Leaky Abstractions isn't going anywhere. The technologies change, but the principle remains: you can abstract complexity, but you can't eliminate it. It's still there, waiting for the moment you need to understand it.