A deploy of a Next.js app to Cloudflare Workers through OpenNext can finish green and still break the live site, because green covers only two things: the app compiled and the Worker files were uploaded. Nothing in that run asks the new Worker for a page, compares its settings with the old ones or looks at DNS. The loud form of the problem is an update after which every page returns HTTP 500 while the Worker log reports an unexpected call to loadManifest(/.next/server/preview-props.json). The quiet forms are a feature that switched itself off a few days after a deploy, and a DNS record of a custom domain that changed when a CI job shipped. Below are five causes we met on our own sites, how to recognise each one, and a check after the deploy that is able to fail.
What the green tick covers
The OpenNext command line has a build step that runs the build script from package.json and then rewrites the output for the Workers runtime; its deploy command wraps wrangler deploy, and its upload command wraps wrangler versions upload and leaves the new version unserved (OpenNext CLI reference). Each of those steps can succeed without a single request reaching the result. The exit code tells you about files. Whether people can open the site is a separate question, and only a request answers it.
A release also leaves things behind that no exit code reports. Each one writes its page cache into a fresh folder in R2, and those folders stay until someone clears them out, which is a slow storage problem rather than an outage, so it sits outside this guide.
1. A pair of releases that fails on every page
On 11 October 2026 an app of ours ran next 16.4.0 with the adapter, @opennextjs/cloudflare, at 1.20.10. The build passed, the deploy passed, and every page came back as HTTP 500 with the loadManifest error in the log. The same code on next 16.3.8 answered normally. Our code had not changed; the combination of the two packages was the cause.
That adapter release declares that it accepts any next from 16.3.8 upward (npm registry document of the adapter), so npm had no reason to warn. A satisfied peer range tells you the authors did not exclude a version. It is not a promise that anyone served it.
Two habits follow. First, write both packages as exact versions in package.json, with no ^ or ~ in front:
"dependencies": {
"@opennextjs/cloudflare": "1.20.17",
"next": "16.4.6"
}
npm install --save-exact @opennextjs/cloudflare@1.20.17 next@16.4.6 writes them that way. A caret lets an install without the lock file, a regenerated lock file or an npm update pick a release that nobody on the team has served yet. Second, try each new release of either package on a throwaway Worker with its own name before production sees it: open a handful of pages, send a form, load a page that reads from your database or bucket, and search the log for loadManifest. When the throwaway behaves like production, move production.
2. Rolling back trades the outage for advisories
The quick cure for the outage is to go back to the release that worked. The trouble is what that release carries. Advisories for the next package list everything from 16.0.0 to 16.4.0 as affected, which includes the 16.3.8 that worked for us, and 16.4.1 as the first fixed release of the line. Among them are a critical flaw that allows remote code execution through use cache functions returning typed arrays (GHSA-673q-mjm6-r5xr) and a high-severity denial of service for App Router apps with Server Actions (GHSA-p3m5-59mp-jv5r). Each advisory spells out which apps it hits, so read the conditions, and still plan to leave the old release within days.
The adapter moves in the same direction. The OpenNext site says that it raises the lowest supported Next.js whenever Next.js ships security fixes, and it sends you to the adapter's peer dependency for the exact range (OpenNext on Cloudflare). In the public registry, release 1.20.12 asks for next >=16.4.1, releases from 1.20.16 on ask for next >=16.4.5, and every release from 1.20.10 on asks for wrangler ^4.148.0 (npm registry document of the adapter). Raising one package alone can leave another below its line, so read the peer range of the target release before you bump anything.
Our own way out was next@16.4.6 with @opennextjs/cloudflare@1.20.17. We tried that pair on a throwaway Worker first, with every page requested twice, a burst of parallel requests and a form, saw no loadManifest error, and production has run on it since 17 November 2026. A newer adapter release, 1.20.18, appeared in the registry on 20 November 2026 (npm registry document of the adapter); we have not tried it, and the same trial applies to it.
One more trap sits on the way up. A next build on 16.4.3 once stopped with a SecurityFatalError and suggested running next upgrade --agent=security. We did not run it. A tool that decides the target release on its own skips both habits above, the exact pin and the throwaway trial, so we raised the version ourselves with --save-exact and tried it like any other release.
3. A buildCommand that skips your own checks
By default OpenNext builds through the project's own build script. Its full configuration example notes that the default is npm run build and shows buildCommand as the way to replace it (OpenNext configuration example). Projects set it for sound reasons, for instance to force a bundler with next build --webpack. The side effect is easy to miss: whatever your build script runs around next build, such as lint, unit tests, a type check or a script that validates redirects, no longer runs during the deploy. The deploy then turns green on a codebase that your own checks would have stopped.
Open open-next.config.ts. If buildCommand calls next directly, either point it at npm run build and move the bundler flag into that script, or keep it and run npm run build as its own step before the OpenNext build. To prove the repair, break one lint rule on a branch and confirm that the deploy step now fails.
4. A value that lives only in the dashboard
The Wrangler documentation is direct about this: environment variables changed in the dashboard are replaced by Wrangler on the next deploy, unless the config sets keep_vars = true (Wrangler configuration). Secrets are a separate case, and the command reference says a deployment never deletes them (wrangler deploy flags). The risk is a plain variable, typically a feature flag that someone switched on by hand during an urgent fix.
The symptom arrives later. A feature stops working days after the change, at a deploy that touched something unrelated, and nobody links the two. The cure is to give every value the Worker reads a home in the repository: vars in the wrangler config for plain values, wrangler secret put for sensitive ones, set on each environment you deploy to. keep_vars is there for the case where the dashboard has to stay the owner of a value on purpose, but such a value is then invisible to git and to review, so we use it only when someone has decided that in writing. Before a deploy, compare the variables the dashboard shows for the Worker with the config file; a name that exists only in the dashboard is the next one to vanish.
5. A CI deploy that rewrites DNS
A Worker attached to a custom domain owns DNS records, because Cloudflare creates them for that hostname on your behalf (Custom Domains). We measured on 6 November 2026, with wrangler 4.156, what happens when wrangler deploy runs with no terminal attached, as it does on a CI runner, in a script or in an agent's shell: the request for each custom domain carried override_existing_dns_record: true. There was no prompt, since there was nobody to ask. The OpenNext deploy command goes through the same wrangler deploy.
In CI we therefore split the release in two. The OpenNext upload makes a new version without serving it, and wrangler versions deploy then moves traffic to it. Cloudflare documents both halves: a plain deploy creates a version and sends all traffic to it at once, and the two steps can also be run apart (Versions and deployments).
- run: npx opennextjs-cloudflare upload
# the upload prints the new version id; pass it on, or read it with: npx wrangler versions list
- run: npx wrangler versions deploy "<new-version-id>@100%" --yes
The same command reference lists a --tag flag for uploads and a --version-tag flag for promotion, which saves you from parsing the id, and a --strict mode for wrangler deploy that refuses a deploy which could override remote settings when nobody can answer a prompt (wrangler commands). We have not tested either through the OpenNext wrapper, and we do not know whether strict mode covers the DNS case, so it is worth a try on a throwaway Worker, not something we vouch for.
The exception is a Durable Object migration. Cloudflare states that changes to Durable Object classes are applied only by wrangler deploy, and that wrangler versions upload does not apply them (Durable Object migrations). The source of wrangler 4.156, which we went through on 22 November 2026, makes the upload give up when a migration is pending, and its error message names that migration, so the pipeline fails and no version exists. Such a commit needs one full deploy, and a human has to start it from their own terminal rather than leave it to the runner.
If that migration deletes a class, it wipes all objects of that class and the data they hold, and there is no undo (legacy migrations). Make sure no code still binds to the class before anyone runs it.
A check after each deploy that can fail
- Request a set of real pages on the live hostname, each with a random query string so that no cache answers for the Worker, and check both the status and a piece of text that must be on the page. A status alone can belong to an error page. Include one page that reads data and one form.
- Count the answers your own script received, not the events in
wrangler tail. In one of our runs the tail caught between 47 and 73 of 79 requests and printed nothing on stderr. We wait about 0.7 seconds after each request and trust only the count on the sending side. - Prove the check can fail. Run it once against the throwaway Worker on the bad pair, or against a path that must not exist, and watch it turn red. A check that has never failed has not shown that it can.
- Add a parallel round. A site can pass one request at a time and fail under a burst, which is how a Workers site of ours lost half its pages to errors when a crawler arrived.
- For a CI job on custom domains, export the DNS records of those hostnames before the new job runs for the first time and compare them afterwards.
When this does not apply
- Next.js on Vercel, Netlify or your own server. The Cloudflare adapter and wrangler are not in the path there, though exact pins and a trial before production still pay off.
- Other versions than ours. The version facts come from a handful of our own Next.js apps on Workers, with one owner, at the dates given. Newer releases of either package may fix the failing pair or bring a new one, so read the peer range and the advisory list for what you actually install.
- An app that never hits the trigger. We saw the outage on our apps but did not isolate which feature of Next.js sets it off, so an app that uses less of the framework might never see it.
- A Worker without a custom domain, or a deploy that a person runs by hand. The DNS point needs both a custom domain and a deploy with no terminal. A Durable Object migration still blocks the upload route either way.
- Newer wrangler. We measured the DNS override on one wrangler version and read the migration behaviour in the source of one version, and repeated neither on later releases.
- Mistakes in the application code. Declaring the edge runtime in a route and similar traps belong to the code, not the deploy; our review of planted Worker pitfalls covers that side.
Our skills for this topic
- opennext-cloudflare-deploy-review reads the files that decide what a deploy does: the dependency versions and scripts in
package.json,open-next.config.ts, the Wrangler settings and your pipeline definition. It points out ranges on the two packages, pairs known to fail or never tried, version floors that are not met, a build override that drops your checks, settings that exist only in the dashboard, a pipeline deploy that can touch DNS and a Durable Object migration sent through the upload route. Each finding comes with a fix, and a review ends with one verdict line. - workers-pitfalls-review looks at the Worker code itself: the edge runtime under OpenNext, D1 queries that outgrow the limit on bound parameters, outbound fetches that miss a failed answer because nothing was thrown, and other traps that pass local tests.
- nextjs-cache-review checks App Router caching on the same stack: ISR that never starts, cache keys that outlive the shape of their data, tag invalidation on every write and redirects laid over cached missing pages.
Read this post as Markdown: /blog/opennext-cloudflare-deploy-green-build-500.md · Atom feed.
