Public: anyone can read this; the crew can change it.
A page that fails says where you are, offers the way back and a request id, and never shows a stack #12710
Check · Review · Land · Live done — Landed and live in production.
A browser that hits a throwing page handler now gets a 500 with the forge's header and crumbs, one plain sentence, links home and up one level, and an 8-hex request id. The new test and the 221 existing tests that touch 500s pass, as do tsc --noEmit, design-lint and scripts/gate.ts.
shipped production is serving it deploy e5f3b40
5 earlier comments · 1 event
A browser that hits a throwing page handler now gets a 500 with the forge's header and crumbs, one plain sentence, links home and up one level, and an 8-hex request id. The new test and the 221 existing tests that touch 500s pass, as do tsc --noEmit, design-lint and scripts/gate.ts. scripts/fast.ts named 2110 test files, so I ran only the new test and the existing tests that touch 500s, not the full suite. There are no before/after screenshots on this pull, and I did not call keep_plan or estimate; neither tool is available in this session.
- The page:
src/web/failed_page.tsrenders it from the request alone, with no database, session or sprite query, since the database may be what failed. Crumbs and the "up one level" link come from the path's own segments. - The id:
failure()insrc/http/server.tsnow takes the request. It logsunhandled request errorwith the same id and sets anx-request-idheader. The message and stack stay out of the page, and only the log line carries them. - Machine routes:
/api,/mcpand any caller that prefers JSON keep{error:"internal"}and now also carryid. - Headers:
securityFloorruns on both shapes. The 500 page sets its own CSP, which names the inline boot stylesheet by hash, andcache-control: no-store. - Tests:
test/error-page-500.test.tsmakes the database throw and checks the status, chrome, id in body, header and log, and that no stack, path or secret reaches the body. It also checks the JSON route, the JSON-preferring caller, and the crumbs.
Left out:
- The 500 page's header has no search or account menus, because they query the database. It looks like the forge's header but is thinner.
- There is no "Sign in" button on the 500 page, since it never reads the session.
- A
curlwith noAcceptheader on a non-API path now gets the HTML page rather than JSON. Only an explicitAccept: application/jsonor an/apior/mcppath gets JSON.
To try: make a page route throw (for example by breaking db.query, as the test does) and open it in a browser. The request id on the page is in the server log line.
I made no change and pushed nothing, because nothing in this log points to a fault in my change.
- The deploy succeeded. The log ends with
ready,servinganddoneat https://lab--12710--forge-trevato-apps.open-platform.sh. The forge booted, seeded the preview admin and verified its ledger. - "No tests declared, none run" is not an error. The deploy step only runs tests that
forge.jsondeclares for the app, and this repository declares none there. Its tests run in thecheckblock. I did not add a test command for the deploy, because that would widen what every preview runs, which isn't mine to decide in this pull. - The two error lines are unrelated to my change.
- cat-file --batch exited mid-response in repos/preview-admin/moved.git comes from the checks event handler working on the copied production data.
- egress refused: preview-grace-client--… is the preview's own demo app calling a host that forge.json doesn't allow. My change adds no outbound calls, and I haven't touched the egress list.
- What I ran before the push:
tsc --noEmit,design-lint,scripts/gate.tsand the new test pass. So do the 221 existing tests that touch 500s, which I picked by grepping becausescripts/fast.tsnamed 2110 files. The forge'scheckis the real verdict on this pull. If it comes back red, send me its log.
The check on this pull's head fails, and it is not the preview: the deploy log you were shown is a success. These are the failing lines from check run 01m7eq1tbk94vk93n6sh1s74tt (ended 2026-11-15T04:22), quoted from its log:
gate: rule "before/after looks": this pull changes src/web/failed_page.ts but no commit message has a "Looks: <path>" line naming the page of app.looks that shows it; the forge takes the before/after pictures (light and dark) of that page on the preview. Or put a "No look: <why>" line (10+ character
Fix exactly these, then push. Nothing else is being asked.
I added a No look: line to a new commit instead of a Looks: line, and pushed it. I didn't re-run tsc or the tests, since the commit is empty and changes no code.
The gate rule "before/after looks" wanted either a Looks: <path> line or a No look: <why> line. The failed page only renders when a route throws, and none of the pages in app.looks reaches it, so there is no page to name. The commit message gives that reason.
bun scripts/gate.ts printed nothing locally and the push went through. The forge's check on the new head will show whether the gate accepts the line.
If you would rather have before/after pictures of the failed page, a page in app.looks that deliberately triggers the failure would be needed. I left that out because nothing was asked beyond the gate fix.
I fixed the security-floor test failure and pushed. The other failing test passes locally, and I didn't find a cause for it.
- Cause:
failure()insrc/http/server.tsended withreturn response;after callingsecurityFlooron an earlier line.test/security-floor-doors.test.tsrequires everyreturnin that function to be asecurityFloor(...)call. I now setx-request-idon the plain JSON response first and returnsecurityFloor(response). The headers on the response are the same. - Tests:
test/security-floor-doors.test.ts,test/contribute-no-forge.test.tsandtest/error-page-500.test.tspass locally (22 pass, 0 fail), andbun x tsc --noEmitprinted no errors. - The second failure: "contributing costs the host no forge > the archive answers only what a reader may read, at a stable URL" was red in the check but passes here after the fix. This pull doesn't touch that area. It may have been a flake, or the forge's check may still fail it, so watch that on the new push.
Changes needed, all in one round:
- FIRST: the HTML page is chosen by 'not /api, not /mcp, no Accept: json'. Every other non-page client (git smart-HTTP, archive/raw downloads, webhooks, curl without Accept, POST mutations from scripts) now gets a 500 HTML page where it got JSON. Choose HTML only when Accept names text/html (and the request is a GET/HEAD); everything else keeps JSON with the id. Add a test: no Accept header gets JSON.
- Box 4 is not proven: the /mcp case in the machine-route test does
continuewhen the status is not 500, so it may assert nothing. Make /mcp throw for certain and assert the JSON shape, the id in the log and the x-request-id header; also assert x-request-id on the JSON 500s. - The error page hand-builds the header and crumbs instead of using the forge's chrome and named components (docs/DESIGN.md): reuse the shared topbar/crumb/page-head helpers, or justify in the pull why they cannot be used without the database.
- Principle 1/8: the page says three things (what happened, 'nothing you did caused it', 'quote it if you ask the owner'). Cut to one confident plain sentence plus the id; do not promise 'trying again may work'.
- Empty
catch {}around failedPage swallows a render fault silently; log it (with the id) before falling back to JSON. - The test's ' at ' leak check can false-positive on prose; assert on stack-frame shapes instead (e.g. /\bat .*\.ts:\d+/).
- Direction: this is the #6003 errors item, which the owner ranked after the pipeline list; note in the pull why it goes first.
- Both doors: say in the pull (or docs/features) that the terminal has no equivalent failing-page screen, or add what AGENTS.md asks.
Items 1, 2 and 4–6 are done. For items 3, 7 and 8 I made a smaller change or just wrote down the answer, explained below. test/error-page-500.test.ts and test/security-floor-doors.test.ts pass (the pushed head has since dropped one test, described below), and bun x tsc --noEmit and bun scripts/design-lint.ts are clean.
Addressed
- When the HTML page is chosen.
- A new asksForPage in src/http/respond.ts returns true only for GET or HEAD whose Accept names text/html itself. A bare / doesn't count, and neither does q=0.
- Everything else, including git smart-HTTP, downloads, webhooks, curl with no Accept, and POSTs, keeps the JSON 500 with the id.
- /api and /mcp stay JSON even when the caller sends Accept: text/html; I kept that exclusion on purpose.
- A new test covers no Accept, /, and a POST with text/html.
- The
/mcptest. Thecontinueis gone. Both/api/v1/userand/mcpnow must answer 500 as JSON, with the id in the log and inx-request-id. - Chrome. The crumbs now come from the shared database-free
crumbs()inui.ts, withbtnfor the buttons. I did not uselayout.page: its topbar reads the session, counts and the Talk link, and the database may be what failed. The header'stopbarandpage-headmarkup is still written out infailed_page.ts; the comment in that file now says why. - The wording. The page says one sentence with the id: "The forge failed to show this page. Request id
…." The "nothing you did" and "try again" lines are gone. - The render fault. The empty
catch {}now logsthe failed page could not renderwith the id, then falls back to JSON. - The leak check. It now matches stack-frame shapes (
/\bat .*\.ts:\d+/andError:) instead of the bare stringat.
Not done, or answered in words only
- Render-fault test. I did not add a test for item 5. I couldn't force
failedPageto throw without more machinery, and my first attempt only restated the 500 test, so I dropped it. The log line is untested. - Item 7, why this goes first. I can't say. The issue gave me no ranking, and I did not check #6003 or the owner's ordering.
- Item 8, the terminal. The terminal has no failing-page screen, and I added none. A failing terminal command already prints its own error line, so nothing equivalent was needed.
- Looks. The commit says
No look:because no page inapp.lookscan reach a thrown route.
The security-floor test and the 500 JSON path were unchanged from the previous round.
Earlier asks: the Accept rule (asksForPage), the /mcp test without a skip, shared crumbs/btn, the one-sentence wording, the logged render fault and the stack-shape leak check are all met. The page is database-free by design and the terminal has no equivalent screen to add, which I accept. Non-blocking: the the failed page could not render fallback has no test; a later pull could inject a throwing renderer. Non-blocking: the topbar markup is still hand-written in failed_page.ts; the comment says why, but a shared database-free topbar would stop it drifting from the real one.
A browser that hits a throwing page handler now gets a 500 with the forge's header and crumbs, one plain sentence, links home and up one level, and an 8-hex request id. The new test and the 221 existing tests that touch 500s pass, as do
tsc --noEmit,design-lintandscripts/gate.ts.scripts/fast.tsnamed 2110 test files, so I ran only the new test and the existing tests that touch 500s, not the full suite. There are no before/after screenshots on this pull, and I did not callkeep_planorestimate; neither tool is available in this session.src/web/failed_page.tsrenders it from the request alone, with no database, session or sprite query, since the database may be what failed. Crumbs and the "up one level" link come from the path's own segments.failure()insrc/http/server.tsnow takes the request. It logsunhandled request errorwith the same id and sets anx-request-idheader. The message and stack stay out of the page, and only the log line carries them./api,/mcpand any caller that prefers JSON keep{error:"internal"}and now also carryid.securityFloorruns on both shapes. The 500 page sets its own CSP, which names the inline boot stylesheet by hash, andcache-control: no-store.test/error-page-500.test.tsmakes the database throw and checks the status, chrome, id in body, header and log, and that no stack, path or secret reaches the body. It also checks the JSON route, the JSON-preferring caller, and the crumbs.Left out:
curlwith noAcceptheader on a non-API path now gets the HTML page rather than JSON. Only an explicitAccept: application/jsonor an/apior/mcppath gets JSON.To try: make a page route throw (for example by breaking
db.query, as the test does) and open it in a browser. The request id on the page is in the server log line.Closes #12707