How to Read Vercel's New Build Cache Numbers: Billable Uploads and Cold Starts

If your Vercel builds got slower this week, check the build cache numbers on the deployment summary before you touch anything else. Since October 21, 2026, every deployment summary shows the size of the build cache that deployment saved and how close it sits to the limit for its build machine, and per Vercel’s changelog of October 23, 2026, “Uploading the build cache is billable build time, and a cache that goes over the limit is discarded, so the next build starts without one.” Those two sentences change what a dependency cache is: not free speed, but a budgeted resource with a hard threshold and a standing cost.

One caveat up front, because it shapes how much weight any of this can bear: everything substantive in this article comes from that single vendor changelog and Vercel’s own platform page. The discard behavior, the billing treatment, and the limit mechanics are vendor-claimed until Vercel’s docs and independent community reports confirm them. Where the changelog is silent, I say so rather than guess.

What changed, and where to read it

The changelog describes a display change with an economic one attached. “Deployment summaries now show the size of the build cache each deployment saved and how close it is to the limit for its build machine.” The same data is exposed on two automation surfaces: “The same information is in the CLI with vercel inspect on version 65.1.0 or newer, and in the get-deployment REST API endpoint.” And the rollout is not opt-in: “This is on by default on all plans for deployments built on or after October 21. See the maximum build cache size for each build machine in the docs.”

That last sentence matters for two reasons. First, the limit is per build machine, not one global number, so a team on different machine sizes can see different thresholds across projects. Second, Vercel’s docs page lists the per-machine limits, but those values are not verified here, so I will not quote any limit figure. Read your own numbers from the surfaces below rather than anyone’s remembered default.

The CLI and REST surfaces fit naturally into how teams already drive Vercel. Deployments run through Git repositories, the Vercel CLI, or the REST API, as Wikipedia’s Vercel entry confirms, so the cache metrics arrive on the same channels your automation already uses. There is no new system to adopt; there is a new field to read.

The mechanism: billable uploads and the discard rule

The changelog’s mechanism has three moving parts, and each has a distinct cost profile:

1. Saving the cache costs money. Upload time counts as billable build time. A bigger cache means a bigger upload, on every build that writes one, whether or not the next build ever reads it back.
2. The cache has a per-machine size limit. The changelog defers the values to docs; what it states is that a limit exists per build machine.
3. Crossing the limit forfeits the cache entirely. An over-limit cache is discarded, so the next build starts cold and pays full dependency-install and compile time, and then, presumably, pays again to upload a fresh cache.

The economics that follow are worth stating plainly. A cache just under the limit costs you upload time on every build and saves you install time on most builds. A cache that crosses the limit is discarded, so it saves nothing for the next build and hands that build a cold start; whether you are also billed for uploading a cache that is then discarded is an open question I come back to below. Either way, the worst place to sit is just past the threshold, where you receive none of the cache’s benefit and may be paying for the upload besides. That makes “how close is it to the limit” the more important of the two new numbers, because it measures your distance from the cliff, not just your current spend.

Treating cache bytes as a budgeted resource with threshold-triggered eviction is a familiar systems pattern, not a Vercel invention. In Linux, each cgroup’s page-cache pages are charged to that cgroup’s memory allocation and evicted when its threshold is reached; a recent eBPF page-eviction paper describes “its own set of page cache lists which count toward its memory allocation, allowing for cgroup-specific eviction when its memory threshold is reached.” That paper is about Linux, not Vercel, and it tells you nothing about Vercel’s implementation. What it does establish is that per-scope cache budgets with hard eviction thresholds are standard engineering practice. Vercel’s per-build-machine limit is an ordinary instance of that pattern, which is a reason to take the mechanism seriously rather than to be surprised by it.

Reading a suddenly slow build: three hypotheses

The new numbers give you a way to triage a build that doubled in duration. This diagnosis flow is my inference from the changelog’s mechanism, not a procedure Vercel published, so treat it as reasoning to test against your own deployments.

Hypothesis one: the cache was discarded. Check the previous deployment’s saved cache size against its limit proximity. If it was at or over the limit, the changelog’s discard rule explains the slow build: this one ran cold, and you should expect it to have uploaded a fresh, full cache afterward. The tell is a slow build followed by a return to normal, with a large cache size on the slow deployment itself.

Hypothesis two: you are paying for upload, not losing the cache. If builds are consistently a bit slower or billable minutes are drifting up without any dramatic cold builds, look at the cache size trend. A growing cache that stays under its limit still uploads on every build that writes it, and that upload is billable time. This is the slow bleed rather than the cliff.

Hypothesis three: something else changed. The changelog cannot rule out an unrelated cause: a dependency update, a lockfile change, a code change that invalidated a framework-level cache layer. If the cache numbers look stable and well under the limit, the new metrics have done their job by eliminating the discard hypothesis, and you debug the build the way you would have last month.

The practical difference between hypotheses one and two is the difference between pruning now and budgeting for later. Both point the same direction, though: a cache that is large relative to its limit is either a cold start waiting to happen or a standing charge you should justify.

What to prune, and why one fat artifact dominates

The angle most teams will reach for is pruning or splitting: trimming node_modules growth, reconsidering how much .next output the build cache carries, or moving Docker layers out of the default cache path in monorepos. The changelog does not enumerate what counts toward the cache, so treat those as the usual suspects in a Next.js-on-Vercel build, not as a documented inventory.

There is a general caching principle that explains why this kind of pruning pays disproportionately, and it comes with the same not-about-Vercel caveat. Researchers studying NGINX proxy caches describe default recency-based eviction as size-blind: “LRU is catastrophically myopic. It is size-blind (a single 120 MB video can evict thousands of popular 20 KB assets), periodicity-blind (daily traffic bursts cause thrashing just before predictable requests), and assumption-bound (it assumes recency correlates with future value—a correlation that adversaries and real workloads routinely violate),” as the Cold-RL cache-eviction paper puts it. That is a statement about proxy caches under LRU, and Vercel’s changelog says nothing about eviction policy inside the limit; it says the whole cache is discarded when the limit is crossed, which is simpler and harsher. But the underlying lesson transfers: in a size-limited cache, one large, low-value artifact dominates the budget. A monorepo where one workspace’s dependency tree or build output swells can consume the headroom that every other workspace’s reuse depends on. Pruning the biggest contributor is usually worth more than trimming ten small ones.

Where heavy caches can live instead

If the answer is relocation rather than reduction, Vercel’s platform pages name two candidates, but neither page says where the heavy caches actually live. The Vercel platform page advertises “Full Docker support via the Vercel Container Registry, so Rails, PHP, Java, and .NET now all run natively on Vercel.” That is a statement about running containers, not about caching: it says nothing about whether images pushed to the registry count toward the build cache or bypass it, so whether the Container Registry is a real relocation target for layer caches is a question to answer in Vercel’s docs before acting on it. For monorepos, Vercel says Turborepo powers its monorepo builds; Wikipedia independently confirms that Vercel acquired Turborepo in December 2021. How Turborepo’s caching actually works is not something I could verify from these sources, so treat per-package cache splitting as a hypothesis to check in the docs rather than a documented escape hatch.

I want to be careful here. A comparison against GitHub Actions cache limits and external Docker layer caching would answer the relocation question more directly, but I could not verify GitHub Actions’ current cache quotas or eviction behavior, so I will not assert numbers or claim that one platform is more generous than another. What I can say is structural: any hosted build system with a size-limited cache faces the same budget arithmetic, and the right question is never “which platform caches more” but “which cache do my heaviest artifacts actually need to live in.” If you are weighing a move of Docker layers or monorepo artifacts between Vercel and an external CI, verify both sides’ current limits in their docs before deciding. That verification step is a consequence of the evidence gap, not a formality.

Monitoring the limit before it bites

Because the discard rule turns limit proximity into an incident predictor, the CLI and REST surfaces are the durable part of this change. The dashboard tells you what happened; vercel inspect and the get-deployment endpoint let you ask the question on a schedule.

A reasonable setup, stated as a hypothetical with its assumptions: suppose your team deploys a Next.js app a dozen times a day and your cache has been growing a few percent a month as dependencies accumulate. A weekly job that calls the get-deployment endpoint for the latest production deployment, reads the cache size and limit proximity, and posts a warning when proximity crosses some internal threshold, say 80 percent, gives you weeks of notice before a discard forces a cold build during a busy deploy window. The 80 percent figure is my arbitrary example, not a Vercel recommendation; the right trigger depends on your cache’s growth rate, which the new numbers now let you measure. The changelog does not document the exact field names in the REST response or CLI output, so confirm those against the current API reference before automating.

One open billing question makes monitoring slightly more urgent. The changelog says cache upload is billable and that an over-limit cache is discarded, but it does not say whether you are still billed for uploading a cache that is then discarded, or whether the discard happens at save time or restore time. If the upload of a doomed cache is billed, crossing the limit is strictly worse than it first appears: you pay for the upload, lose the cache, and pay for the cold build. That is vendor silence, not vendor policy, and it is exactly the kind of edge case to test on a non-critical project or raise with Vercel support rather than assume.

What this evidence cannot settle

Everything above rests on one changelog published two days ago, plus Vercel marketing pages and academic papers about other systems’ caches. Specifically unverified as of this writing:

• The actual per-machine limit values, which Vercel’s docs page lists but which are not verified here.
• Whether a discarded cache’s upload is billed, and whether discard happens at save or restore.
• Any independent confirmation: I found no community reports, blog posts, or third-party coverage of cold builds caused by the discard rule.
• Any comparison of Vercel’s limits against GitHub Actions or external Docker registries.

None of that invalidates the mechanism Vercel describes, but it does mean you should verify the numbers that matter to your bill against the docs and your own deployment data before restructuring anything around them.

The practical read

Read the new numbers now, because they are already on every deployment you have built since October 21. If your cache sits comfortably under its limit and build minutes are stable, the correct action is to add a proximity check to whatever monitoring you already run and move on. If your cache is creeping toward the limit, prune the largest contributor first, because in any size-limited cache the biggest artifact consumes the most budget, and here the penalty for crossing the line is not gradual degradation but a discarded cache and a cold build. And if your build minutes are climbing without an obvious cause, the cache-upload line is now a first-class suspect, because Vercel tells you it is billable.

I would not restructure a monorepo or migrate Docker layers off-platform on the strength of this changelog alone. I would instrument limit proximity this week, fix whatever is closest to the threshold, and let a month of your own cache-size data, plus whatever the docs and community reports add, decide the bigger moves. The discard rule makes cache size a budget line whether you manage it or not; the only choice is whether you see the bill coming.

Frequently Asked Questions

Where can I find the build cache size and limit proximity for a deployment?

The same information is in the CLI with vercel inspect on version 65.1.0 or newer, and in the get-deployment REST API endpoint.

Is the build cache size display available on all Vercel plans?

This is on by default on all plans for deployments built on or after October 21. See the maximum build cache size for each build machine in the docs.

What happens if the build cache exceeds the limit for the build machine?

Uploading the build cache is billable build time, and a cache that goes over the limit is discarded, so the next build starts without one.