docs(troubleshooting): list the headers a custom CORS allow-list must include

[PMerlet]

Related to PRD-892 (Forest-Projection header for get-one projections).

When a host application answers the CORS preflight itself with an explicit allowedHeaders list, the new Forest-Projection header must be included or the record details view breaks once the agent announces the canUseProjectionViaHeader capability. This documents the full list of headers such an allow-list must contain, in the CORS section of the troubleshooting guide.

Agent PR: ForestAdmin/agent-nodejs#1813 · Front PR: ForestAdmin/forestadmin#9893

🤖 Generated with Claude Code

Note

Document required headers for custom CORS allowedHeaders lists in troubleshooting guide

Adds a bullet to the CORS section of troubleshooting.mdx specifying that a custom allowedHeaders list must include Authorization, Content-Type, Forest-Context-Url, and Forest-Projection. Omitting Forest-Projection breaks the record details view; omitting the others blocks preflight requests entirely.

Changes since #24 opened

• Rewrote CORS troubleshooting documentation to specify required headers and preflight handling [27e02d4]

^{Macroscope summarized b15eae2.}

Important

Merge order: do not merge before ForestAdmin/agent-nodejs#1813 and ForestAdmin/forestadmin#9893 — the Forest-Projection guidance only becomes true once agents announce the canUseProjectionViaHeader capability.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
forest	🟢 Ready	View Preview	Aug 10, 2026, 2:08 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[linear-code]

PRD-892

[hercemer42]

Claude Fable 5 (claude-fable-5): Should fix

"A missing entry blocks the preflight" is mechanically backwards, and on this page that matters: the OPTIONS request itself succeeds (204 from express cors and @koa/cors alike) — the browser then rejects the preflight response and cancels the actual request, which is never sent.

Line 8 of this page tells the reader to open the Network tab to diagnose. Told that the preflight is "blocked", they'll scan for a failing OPTIONS row, see 204 on every one, and rule the allow-list out — the exact misdiagnosis this bullet exists to prevent. The real signal is the cancelled GET and the console error Request header field forest-projection is not allowed by Access-Control-Allow-Headers in preflight response.

Suggested rewording: "…the browser rejects the preflight response and cancels the request (the OPTIONS row still shows 204 — look for the console error naming the header)." Naming the console string also gives readers something to search for.

[PMerlet]

Right — the misdiagnosis path you describe is exactly what the page's own "open the Network tab" advice would trigger. Fixed in 27e02d4: the bullet now states that the OPTIONS request still returns 204, that the browser rejects the preflight response and cancels the actual request, and it quotes the console error verbatim so readers have a string to search for.

[hercemer42]

Claude Fable 5 (claude-fable-5): Should fix

"a missing Forest-Projection breaks the record details view" is stated as current behaviour, but it only becomes true once agent-nodejs#1813 and forestadmin#9893 ship and the agent announces canUseProjectionViaHeader — on every released agent today the header is never sent, so its absence breaks nothing.

Consequence: a reader whose details view is broken right now adds Forest-Projection, observes zero change, and the page loses credibility on the other three headers — which are correct today.

Zero-cost fix that also encodes the merge-order dependency: "…a missing Forest-Projection breaks the record details view on agents that announce the canUseProjectionViaHeader capability." And this PR shouldn't merge ahead of the two code PRs.

[PMerlet]

Fixed in 27e02d4: the impact is now scoped to "agents that announce the canUseProjectionViaHeader capability". The merge-order dependency is also recorded in the PR body — this PR must not merge before ForestAdmin/agent-nodejs#1813 and ForestAdmin/forestadmin#9893.

[hercemer42]

Claude Fable 5 (claude-fable-5): Preferential

Two wording points on the same sentence:

1. "every header the Forest UI sends" is a closed-set claim the UI doesn't honor: it also sends Accept: application/json on every agent request (basic-adapter.js/authenticated-server-fetch.ts — CORS-safelisted, so the four listed headers remain the correct allowedHeaders value), and smart views / custom action code can pass arbitrary extra headers through lianaServerFetch. "every header the Forest UI sends that requires allow-listing" keeps the instruction exact without the false promise.

2. This bullet only applies when the reader has not followed the bullet directly above it (agent mounted first → @koa/cors reflects Access-Control-Request-Headers and the host allow-list is never consulted). Sequenced as sibling checks, a reader who mounted the agent first can still add four headers and observe nothing. Opening with the fallback framing — "If you cannot mount the agent first and your own CORS middleware answers the preflight…" — plus the tell (a fixed Access-Control-Allow-Headers list in the OPTIONS response means your middleware answered; an echo of what was requested means the agent did) lets readers know which case they're in.

[PMerlet]

Both taken in 27e02d4: the bullet opens with the fallback framing ("If you cannot mount the agent first and your own CORS middleware answers the preflight requests…"), the list is qualified as "every header the Forest UI sends that requires allow-listing", and it closes with the tell — a fixed Access-Control-Allow-Headers list comes from the host middleware, an echo of the requested headers comes from the agent.