fix(web): restore /flows and /docs on Next 16.3.8 (fix forward, alternative to #129)

[khaliqgant]

Production incident

/flows and every /docs/<slug> page have returned 500 since #126 (Next.js 16.3.5 → 16.3.8) deployed at 2026-10-02 04:40 UTC.

This is the fix-forward: it keeps Next 16.3.8. #129 is the alternative that pins back to 16.3.5. Merge one and close the other.

Cause

• Next 16.3.8 looks prerendered pages up under a new route-scoped key: /route-cache/<KIND>/<sha256 of source route>/$<page path> (next/dist/server/lib/route-cache-key.js).
• The OpenNext static-assets incremental cache stores them as <build id>/<page path>.cache and passes the key through unchanged, so every lookup misses.
• On a miss the Worker renders the page at request time. Two kinds of page cannot render in the Workers runtime:
  • docs MDX: EvalError: Code generation from strings disallowed for this context
  • /flows: CompileError: WebAssembly.instantiate(): Wasm code generation disallowed by embedder
• Other pages (/, /blog) return 200 only because they survive a live render; they are also missing the cache.

Change

• web/lib/prerender-cache-key.ts: translates a route-scoped key back to its page path; any other key passes through.
• web/open-next.config.ts: wraps the static-assets cache with that translation. The cache name is unchanged, so populateCache still copies the prerenders into assets.
• web/lib/test/prerender-cache-key.test.ts: builds keys with Next's own getRouteCacheKey, so another change to the key shape fails CI.

Verification (local opennextjs-cloudflare build + populateCache local + wrangler dev, Next 16.3.8)

Path	Without this change	With this change
/	200, cache MISS	200, cache HIT
/flows	500	200, cache HIT
/docs/introduction	500	200, cache HIT
/flows/plugins	200, cache MISS	200, cache HIT
/blog	200, cache MISS	200, cache HIT

With the change, /docs/quickstart, /docs/agents/cli, /docs/7.1.1/quickstart, /about and /docs/introduction.md also return 200 from the cache.

• Web tests: 328 passed. tsc --noEmit: clean.
• Not verified on the deployed runtime yet: check /flows and /docs/introduction on this PR's preview URL before merging.

Risk compared with #129

This depends on an internal Next key format and should be removed once @opennextjs/cloudflare handles route-scoped keys itself. #129 returns to the exact dependency set that was healthy in production yesterday.

@khaliqgant — needs the two reviews plus a human merge to deploy.

🤖 Generated with Claude Code

---

Note

^{Cursor Bugbot is generating a summary for commit 5bf3e62. Configure here.}

---

Summary by cubic

Fixes the production 500s on /flows and every /docs/<slug> page that started with the Next.js 16.3.8 upgrade in #126.

Changes

• Wraps the OpenNext static-assets incremental cache to translate Next 16.3.8's route-scoped keys back to the page paths the cache stores them under.
• Tests build keys with Next's own key builder, so a future key-shape change fails CI instead of production.

Risk

• Relies on an internal Next key format; remove once @opennextjs/cloudflare handles route-scoped keys itself.
• Alternative fix(web): pin Next.js back to 16.3.5 to restore /flows and /docs (prod 500s) #129 pins Next back to 16.3.5; merge one and close the other.

^{Written for commit 5bf3e62. Summary will update on new commits.}

---

Agent Relay sessions

• claude session fe983435 · opened via gh pr create · last active 2026-10-02

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 53 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: c180229b-e065-4af1-ae0e-ff1f8dbd97c0

📥 Commits

Reviewing files that changed from the base of the PR and between d590f7a and 5bf3e62.

📒 Files selected for processing (3)

• web/lib/prerender-cache-key.ts
• web/lib/test/prerender-cache-key.test.ts
• web/open-next.config.ts

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

🔍 Devin Review: 1 flag

Not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[github-actions]

Preview deployed!

Environment	URL
Web	https://4718495c-agentrelay-web.agent-workforce.workers.dev

This is a Cloudflare Workers preview version of this PR's build.