Skip to content

fix(server): answer handler defects with a readable 500 instead of an empty one - #64022

Merged
rekram1-node merged 6 commits into
devfrom
readable-500
Nov 16, 2026
Merged

rekram1-node merged 6 commits into
devfrom
readable-500

Conversation

@rekram1-node

@rekram1-node rekram1-node commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Requests that crash in a handler used to get a 500 with an empty body. Now that same 500 carries a JSON body: what went wrong with storage when that is the problem, otherwise a ref to find the crash in the server log. Messages never name the database engine.

POST /api/session/:id/prompt   (disk full)
  before: 500  ""
  after:  500  { "_tag": "UnknownError", "message": "Storage is full", "ref": "err_1a2b3c4d" }

any other crash
  before: 500  ""
  after:  500  { "_tag": "UnknownError", "message": "Server failed to handle the request. Check server logs for details.", "ref": "err_1a2b3c4d" }

How it works

handler fails
  defectResponseLayer (global router middleware)
    HttpServerError.causeResponse(cause)    ← what Effect would answer
    not an empty 500?  → unchanged (declared errors, 404, aborts, defects with their own response)
    empty 500?
      log the cause with a ref
      message = StorageFailure.message(cause) ?? generic text
      fail with [original cause + UnknownError response]
        → Effect sends the response
        → the request span and the response log still record the original defect
StorageFailure.message(cause)                       core/src/database (the only layer that knows SQLite)
  find the SqlError: a failed transaction, or a drizzle query error holding one
  resultCode(sqlError.reason.cause)                 ← each #sqlite module reads its own error type
    bun:      cause instanceof SQLiteError → errno
    node:     one Schema decode → errcode
    workerd:  undefined (no codes)
  primary code →
    FULL               "Storage is full"
    READONLY           "Storage is read-only"
    BUSY, LOCKED       "Storage is in use by another process"
    IOERR              "Storage couldn't be read or written"
    CORRUPT, NOTADB    "Storage is damaged"
    CANTOPEN           "Storage couldn't be opened"
    anything else      undefined → generic message (a buggy query never sends SQL or data)

A rollback no longer hides the storage failure

transaction write hits SQLITE_FULL → SQLite rolls the transaction back itself
  before: our ROLLBACK then fails ("no transaction is active") and replaces the error → generic message
  after:  body failed with FULL / IOERR / BUSY / NOMEM / INTERRUPT (the codes SQLite documents as auto-rollback)?
          → that failed ROLLBACK is expected, report the body's error → "Storage is full"
          any other rollback failure still fails

Changes

 packages/server/src/
   routes.ts
+    Layer.merge(defectResponseLayer)
   middleware/
+    defect-response.ts           # empty 500 → UnknownError, encoded with its schema
 packages/core/src/database/
+  storage-failure.ts             # typed SqlError → storage message, engine never named; rolledBack(cause)
   drizzle/effect-sqlite/session.ts
+    skip the expected failed rollback after an auto-rollback
   sqlite.bun.ts / sqlite.node.ts / sqlite.workerd.ts
+    resultCode(cause)            # the driver's own error type, read once

What doesn't change

  • Status codes and endpoint contracts.
  • Traces: the request span still ends as a failure with the original defect, and the response logger still logs it.
  • Anything that wasn't an empty 500.

New: one error-level log line per crash, carrying the ref the client sees.

Limit

Only some endpoints declare 500 (UnknownError), and the generated client only reads the body on those. session.prompt doesn't, so the client still reports UnexpectedStatus: 500 there. Showing the reason in the TUI on a failed send is a follow-up.

Tests

  • server/test/defect-response.test.ts: a prompt on a real full disk (PRAGMA max_page_count) returns the storage reason, another crash returns the generic message with a ref, and an unknown route still returns 404. Both behavior tests fail without the middleware.
  • core/test/storage-failure.test.ts: a transaction SQLite rolled back itself still reports "Storage is full" and leaves the connection usable (fails without the session fix); real bun errors, including full disk through a statement and a query, an extended code, and non-storage cases (constraint, bad statement, plain defect, interrupt). The node shape is checked under real Node in sqlite-node.test.ts.
  • Server suite 129 pass (isolated HOME), core database tests pass, and bun typecheck in core and server and bun run check pass.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks sound. I copied the new tests into the base checkout and both fail there. With this change they pass: a full disk returns the storage reason, other defects return the generic message with a ref, and an unknown route still returns 404. The full server suite passes (129), and tsc -b is clean for server and core.

Public API: additive and backwards compatible. A handler defect still returns HTTP 500, but now with an UnknownError JSON body (_tag, message, ref) instead of an empty one. No status codes, endpoint contracts or OpenAPI changes.

No blocking concerns. StorageFailure.message only reports a reason for SQLite codes that mean the database can't be used, so query text doesn't leak. Logging the request URL adds no new exposure, since the existing error-response logger already logs URLs for responses of 400 and above.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new commit gates the middleware on HttpServerError.causeResponse producing an empty 500. That limits it to exactly the responses that used to be bodyless, so declared errors, defects that carry their own response, and aborted requests (499/503) keep Effect's answer. The two new tests and the full server suite (129) pass, and tsc -b is clean for server.

Public API: unchanged since the last review and backwards compatible. Only the empty-bodied 500s now carry an UnknownError JSON body (_tag, message, ref).

No new concerns.

Each SQLite driver module now reads its own error into a result code and message: bun:sqlite through its SQLiteError class, node:sqlite through one Schema decode. StorageFailure takes a typed Cause, finds the SqlError behind it and maps the primary result code, instead of probing unknown cause chains. The middleware encodes the response with the UnknownError schema.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No earlier points were open. Storage errors are now found by each #sqlite driver module (bun SQLiteError.errno, a Node error decoded once with a Schema, nothing on workerd) instead of by searching any error's code field. The response is encoded with the UnknownError schema.

Checked: core storage-failure.test.ts and sqlite-node.test.ts pass, including a full disk under real Node. Server defect-response.test.ts and the full server suite (129) pass. tsc -b is clean in core and server.

Public API: unchanged since the last review and backwards compatible. Only 500s that used to have an empty body now return an UnknownError JSON body.

No new concerns.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No earlier points were open. The middleware now fails with the original error plus the JSON response instead of returning the response as a success. Effect sends a response it finds in a failure, so the request span and the response logger still record the original error. CORS headers are still added on this path, since Effect's CORS middleware adds them to every response.

Checked: defect-response.test.ts and the full server suite (129) pass, the core storage-failure tests still pass, and server tsc -b is clean.

Public API: unchanged since the last review and backwards compatible. Only 500s that used to have an empty body now return an UnknownError JSON body.

No new concerns.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No earlier points were open. Storage messages are now fixed wording that never names the database engine (Storage is full, Storage is read-only, …), and the #sqlite modules now return only the numeric result code. Driver text is no longer passed through to clients.

Checked: core storage-failure and sqlite-node tests pass (Node test under real Node), the full server suite (129) passes including defect-response.test.ts, and tsc -b is clean in core and server.

Public API: backwards compatible. 500s that used to have an empty body now return an UnknownError JSON body; since the last review only the storage message wording changed.

No new concerns.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No earlier points were open. The new commit keeps an automatic rollback from hiding the storage failure. Without the session.ts change the new transaction test gets no message instead of "Storage is full", and with it the test passes. Core database/SQLite tests (50, including real Node) and the full server suite (129) pass, and tsc -b is clean in core and server.

Public API: unchanged since the last review and backwards compatible. 500s that used to have an empty body now return an UnknownError JSON body.

One concern, inline: the check for skipping a failed rollback looks at why the body failed, not why the rollback failed, so a rollback that fails for another reason can leave a transaction open on the connection.

// After errors such as SQLITE_FULL, SQLite rolls the whole transaction back itself, so this
// rollback has nothing to undo and fails. Report the body's error, not that one. Any other
// rollback failure still fails.
Effect.catch((error) =>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This checks the body's error, not the rollback's. After FULL/IOERR/BUSY/NOMEM/INTERRUPT, any rollback failure is ignored, including one where SQLite did not roll back and the transaction is still open. A ROLLBACK that hits an I/O error on a failing disk is the likely case. The connection then stays inside an open transaction, so later writes join it or fail with "cannot start a transaction within a transaction". Could this only skip the rollback failure when it's the "no transaction is active" case? For example, check the rollback's own error, or that the connection is back in autocommit, and fail otherwise.

@rekram1-node
rekram1-node merged commit 0fad04b into dev Nov 16, 2026
12 checks passed
@rekram1-node
rekram1-node deleted the readable-500 branch November 16, 2026 02:58
simonklee added a commit that referenced this pull request Nov 16, 2026
Since #64022 the server answers a handler defect with a 500 whose body is
the protocol's UnknownError: a message and a log ref. The TS TUI's
errorMessage shows only the message. Rust toasts showed the declared
error's Display, which puts the tag in front, so a failed prompt, command,
shell, revert or session read said "UnknownError: ...". These toasts now
use tui_message. P-APP C.13/command-defect records the TS toast.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant