fix: never send a stack trace in a server error response; an unavailable remote config is a 502

RA
3h ago
+383-10

Issue for this PR

Closes #1787.

Type of change

  • Bug fix

What does this PR do?

No server error response carries a stack trace, and an unavailable remote config is a 502 that names the remote.

Before this change, altimate-code serve answered any error it didn't recognise with HTTP 500 and the error's full stack (runtime frames, internal file paths) as the message. A wellknown login whose /.well-known/opencode answers an error or refuses the connection made config loading die with an untyped error, so every request failed this way, GET /agent included.

  • Remote config: a failed fetch or read dies with ConfigRemoteUnavailableError { remote, status?, reason }. Both Hono error handlers answer it with HTTP 502 and those fields, and the CLI prints "Failed to load remote config from … : the remote is unavailable (HTTP 503)." remote is the well-known URL, or the remote config's URL template (…?token={env:KEY}), never the substituted URL that can carry the auth token; the HTML-login error (ConfigRemoteAuthError) names it the same way.
  • Unknown errors: both handlers answer with a fixed message and a ref, as the /api HttpApi error middleware already does. Each handler logs the error once, under that ref.
  • Busy session: server.ts answers Session.BusyError with 400 and its message, as middleware.ts already does.
  • Core errors: a NamedError from @opencode-ai/core (it isn't an instance of this package's NamedError) is answered with its own name and fields, not the stack.
  • Session errors: a failed prompt_async publishes the error's message (a NamedError's data.message) without stack-frame lines. The full cause is still logged.

Claims:

  • C1: No response from the Hono error handlers (server.ts, middleware.ts) carries an error's stack, file paths or raw text for an error they don't recognise. The body is { name: "UnknownError", data: { message: <fixed>, ref } }, and the log line carries the same ref.
  • C2: When the remote config answers non-2xx or can't be reached, GET /agent answers 502 with ConfigRemoteUnavailableError naming the remote and its status or transport reason. The response never contains a value substituted into the remote config URL.
  • C3: Errors that already answered with their own name and fields keep their status and body as on main (the 404s, the 400s, RipgrepInvalidPatternError). In middleware.ts, a core NamedError used to fall through to the stack; it now answers with its own fields at 500, or 502 for an unavailable remote config.
  • C4: A failed prompt's session.error event carries the error's message (data.message for a NamedError) without at … frame lines. An error with nothing left falls back to the fixed message.
  • C5: Both Hono handlers answer Session.BusyError with 400 and "Session … is busy", and log every error exactly once, with the ref.

Residuals:

  • R1: An unknown error's message no longer reaches the client, even when the message is harmless. The client gets the ref, and the server log has the full error.
  • R2: In a failed prompt's session.error, any line of the error's message that starts with whitespace and at is dropped as a stack frame, even when it is message text.
  • R3: /api routes (HttpApi) still answer an unavailable remote config with an empty HTTP 500, as on main: the remote config is read while the instance loads (InstanceContextMiddleware → InstanceStore.load), before the /api error middleware sees the defect. No stack or remote text reaches the client there (tested). A 502 on /api means changing how every /api route answers a failed instance load; that is a follow-up.

How did you verify your code works?

  • Fail on main: the error-handler and full-server tests in test/server/altimate-error-bodies.test.ts, including the template-named remote (main sends the URL with the token).
  • Reproduction: with a wellknown entry pointing at a remote that answers 500, and one pointing at a closed port, no response contains a stack or a file path, and GET /agent answers 502 naming the remote.
  • Local: typecheck clean; the 36 tests in the new file and test/cli/error-format.test.ts pass. server.ts's busy branch has no route-level test (reaching it needs a running prompt loop); middleware.ts's identical branch is tested. 8 server, config and CLI tests fail on this machine on main as well, so they don't come from this change.

Cost side effects

None.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR
  • I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"

🤖 Generated with Claude Code

https://claude.ai/code/session_01VEmKQu1Qn99YbrBzhKdtAr

Summary by CodeRabbit

  • Bug Fixes
    • Remote configuration failures now identify the unavailable remote and explain the reason; unavailable remotes receive an HTTP 502 response.
    • Unexpected server errors now show a generic message and reference instead of exposing internal error details. Full details remain available in server logs.
    • Session error messages no longer expose stack-frame details.
    • Other configuration errors retain their existing status handling and messages.