workerd error: static assets total size exceeds 25 MiB limit

TL;DR: Get the big files out of the asset bundle. Measure which assets dominate the 25 MiB, move images, videos, and downloads to R2 behind your domain, and keep only the small HTML, CSS, and JS in the worker's static assets. The cap is per deploy version and cannot be raised.

workerd error: static assets total size exceeds 25 MiB limit

1. Measure the assets. Sum the sizes of everything in your assets directory and list the largest files.

Expected: a short list of large media or download files accounts for nearly all of the 25 MiB.

1. Move the large files to R2. Upload them to a bucket and serve them from your domain, either with a worker route that proxies the bucket or a direct bucket hostname.

Expected: the assets directory shrinks to small text files.

1. Update references. Point image, video, and download URLs at the new R2-backed locations.

Expected: the site loads every asset from its new home with no 404s.

1. Compress what stays. Minify CSS and JS, compress images, and drop unused files from the assets directory.

Expected: the remaining bundle is comfortably under the cap with headroom for growth.

1. Redeploy.

Expected: the deploy succeeds and the asset manifest lists only the small files.

1. Spot-check the moved assets in a browser, including one large file.

Expected: every page renders and large downloads complete.

Use this when

• the deploy fails with the 25 MiB static asset error
• a marketing site, docs site, or app ships lots of images or videos as static assets
• the asset bundle grew gradually until one deploy tipped over the cap
• you need downloads or media served from the same domain as the worker

Not for this skill when

• the deploy fails on script bundle size rather than static assets
• assets deploy fine but load slowly (that is caching or compression, not the cap)
• you need user uploads stored durably (that is R2 directly, not static assets at all)
• the error is about the number of files rather than total bytes

Variant phrasings

• Cloudflare Workers static assets too large
• "static assets total size exceeds 25 MiB limit"
• workers assets 25 MiB deploy fails
• too many static files worker deploy
• assets exceed size limit Cloudflare Workers

Why it happens

Static assets ship inside the worker's version bundle so they are instantly available at the edge, and the platform caps that bundle at 25 MiB per version to keep deploys fast and isolates light. Media files blow through that cap quickly because a handful of images or one video outweighs an entire site's code. R2 is the storage built for those bytes, so moving them there keeps the fast edge path for code and small assets while big files stream from object storage.

Edge cases

• The cap is per version. Deleting files locally and redeploying fixes it, but every future deploy must stay under it too. Keep a size check in CI.
• R2-backed assets need correct content types. Set them on upload or browsers may download files instead of displaying them.
• Cache headers on R2 objects control edge caching. Set long-lived immutable headers for fingerprinted assets.
• A worker route that proxies R2 still burns subrequests and CPU per asset request. For high-traffic media, prefer direct bucket serving with caching.
• Preview deployments each carry their own asset bundle. A bloated assets directory slows every preview deploy, not just production.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_XAlCssAnaMkiljG6cTzCaQ