Puppeteer on AWS Lambda: the 250 MB package limit

What is actually wrong

Installing puppeteer downloads a full Chromium build into node_modules. Uncompressed, that build alone is larger than the 250 MB Lambda allows for the function code and all of its layers combined. Nothing in the application is at fault; the dependency does not fit in the box.

What AWS Lambda gives you to work with

a function that is handed a request, runs, and is frozen again. The execution environment is reused between invocations but you do not control when it is torn down.

• Packaging: 250 MB unzipped for the function code and every layer attached to it, combined. That is the hard number most PDF deployments run into. A container image raises it to 10 GB but changes how the function is built and pushed.
• Filesystem: the deployment package is read-only. Only /tmp is writable, and it defaults to 512 MB. Anything the process writes there survives for the life of the execution environment, not the invocation, which is a subtle source of both caching wins and stale-state bugs.
• Processes: a child process can be spawned and it lives while the invocation does. When the invocation returns, the environment is frozen mid-execution rather than terminated, so a process that has not exited is simply suspended and resumed on the next call.

The fix, if you are keeping Puppeteer

Split the two things puppeteer bundles. Install puppeteer-core, which is the library with no browser, and get the browser from a package built specifically for this limit: a Chromium compiled for the Lambda base image and stored compressed, which is decompressed into /tmp on the first invocation. The compressed build fits inside a layer.

import chromium from "@sparticuz/chromium";
import puppeteer from "puppeteer-core";

// Decompresses Chromium into /tmp on a cold start. Subsequent
// invocations on the same execution environment reuse it.
const browser = await puppeteer.launch({
  args: chromium.args,
  executablePath: await chromium.executablePath(),
  headless: true,
});

What still hurts after that

The decompression happens on every cold start and it is not free, so p99 latency now has a step in it that p50 does not show. The Chromium build and the puppeteer-core version have to match, and they are released by different people on different schedules, so a routine dependency bump can produce a protocol error that looks like nothing to do with versions. /tmp defaults to 512 MB, which the decompressed browser eats a large share of before your document does. And the layer has to be rebuilt whenever AWS moves the runtime to a new base image, because the binary was compiled against the old one.

What Puppeteer is genuinely good at

it renders exactly what a browser renders, which means modern CSS, web fonts and client-side JavaScript all behave the way they do in a tab. That is worth keeping in view: the problem on this page is where it runs, not what it produces. Puppeteer is a Node library that drives a real Chromium, and downloads that Chromium into node_modules when it is installed. It needs the browser binary, a long list of shared libraries the browser links against, fonts, and enough memory for a browser process that is not accounted for by your runtime's heap settings.

The other shape of the answer

Every fix above keeps the renderer inside your deployment, which means the constraint stays yours: the package size, the shared libraries, the fonts, the memory, the patching. The alternative is an HTTP call from AWS Lambda to something that already has a browser in it, which turns all of the above into a request and a response. That is what this API is, and it is the reason these pages exist. Whether that trade is right depends on whether rendering is a thing you want to operate.

Frequently asked

Related failures

The same platform with a different renderer, and the same renderer on other platforms.