The error envelope
Kata produces one error shape. Every 4xx and 5xx response — validation failures, your own domain errors, output mismatches, uncaught throws — comes back as the same JSON envelope:
type ErrorBody = {
error: string // stable, machine-readable code
message: string // human-readable description
issues?: Record<string, FieldIssue[]> // structured field errors, keyed by input section
}error— the discriminator a client switches on ('not_found','validation_failed','internal_error'). It never holds a human sentence.message— a human-readable description. Always present.issues— present only when there are structured field errors (today: input validation).
Why force every failure into one shape? Because it lets a client write one error handler instead of one per endpoint. Whatever goes wrong, the caller reads error to decide what happened and message to show a human — never guessing at a different body shape for each route. And this is enforced by the runtime, not by convention: both ends of every route are validated, and each failure mode maps to this envelope. The two automatic ones come first; the ones you write come after.
| Stage | When | On failure |
|---|---|---|
| Input | before the handler runs | 422 validation_failed |
| Handler throws | any escape from middleware or handler | 500 internal_error |
| Output | after the handler returns a value | 500 internal_output_shape_mismatch (mode-dependent) |
| Your 4xx | you return c.error(...) / c.json(...) | your status |
A request whose body is non-empty but not valid JSON is rejected before the input stage with 400 validation_failed (message: "Malformed JSON body"); an empty or absent body instead reads as undefined and lets the schema decide.
Unknown route and wrong method: the built-in 404 / 405
Two failures happen before any of the stages above — no route matched, so there is no input schema and no handler of yours to run. Kata answers them itself, through the same envelope, with no configuration required.
A request to a path no route declares answers 404:
{ "error": "not_found", "message": "Route not found" }A request with the wrong method on a path some route does declare answers 405, with an Allow header listing the methods the path accepts:
{ "error": "method_not_allowed", "message": "Method not allowed" }Both run the app-level (global) middleware chain first — the same fallback that lets a global cors() answer an OPTIONS preflight even against a path no route declares (see CORS preflight for how a registered path's preflight is normally answered) — and both pass through the same final step as every other response, so the X-Request-Id correlation header is present here too.
The 422 validation envelope
input is validated before your handler — a 422 is Kata's way of saying "you sent something the route's input schema rejected." On failure Kata never calls the handler; it responds 422 with error: "validation_failed", the message "Request input validation failed", and an issues object keyed by the input section that failed (params / query / body / headers). Each key holds an array of field issues.
For the POST /users body { "name": "", "email": "not-an-email" } against CreateUserBodySchema, the response is (this shape is asserted by examples/hello's users.hurl; the literal message strings are Zod's):
{
"error": "validation_failed",
"message": "Request input validation failed",
"issues": {
"body": [
{ "path": "name", "code": "too_small", "message": "String must contain at least 1 character(s)" },
{ "path": "email", "code": "invalid_string", "message": "Invalid email" }
]
}
}A query failure looks the same, just keyed under query instead of body. This is what an invalid z.enum(...) value produces — the commonest query shape — for GET /todos?status=archived against z.object({ status: z.enum(['open', 'done']) }):
{
"error": "validation_failed",
"message": "Request input validation failed",
"issues": {
"query": [
{
"path": "status",
"code": "invalid_enum_value",
"message": "Invalid enum value. Expected 'open' | 'done', received 'archived'",
"received": "archived"
}
]
}
}The 422 is fixed, and it is not configurable
Automatic schema validation — any input section that fails safeParse — always answers 422. The only automatic 400 is a malformed (non-JSON) body; see Gotchas. Your own c.error(...) is the only thing that can produce a 400, and there is no option, hook, or config anywhere in defineRoute or createApp that changes the automatic 422.
If a contract you're implementing demands 400 for what is really a schema failure, the way out is to loosen the input schema so it always parses, then check the shape by hand in the handler and return c.error(..., { status: 400 }) yourself — trading the automatic check for a manual one that controls its own status.
The FieldIssue shape
Every entry under issues is a FieldIssue:
type FieldIssue = {
path: string // dot/bracket path: "email", "user.profile.age", "items[1].qty"
message: string // Zod's human-readable message
code: string // Zod issue code: "too_small", "invalid_type", "invalid_string", …
expected?: unknown // present when the Zod issue carries it (e.g. invalid_type, invalid_enum_value)
received?: unknown // present when the Zod issue carries it (e.g. invalid_type, invalid_enum_value)
}Rules to keep straight:
pathuses dot notation for nested objects and[n]for array indices. A root-level error has an emptypath: "".expected/receivedappear when the underlying Zod issue carries them (e.g.invalid_type,invalid_enum_value) and are omitted otherwise.- Issues are reported in source order. When more than one section is invalid (e.g. both
paramsandbody), each gets its own key underissues.
Reuse the formatter
If you validate something yourself — a webhook payload, a re-parsed query, a cross-field rule — and want the response to match this exact shape, formatZodIssues(error: ZodError): FieldIssue[] is exported from @katajs-framework/core. Build the envelope with c.error('validation_failed', 'Request input validation failed', { status: 422, issues: { body: formatZodIssues(parsed.error) } }).
Output validation and internal_output_shape_mismatch
When your handler returns a plain value (not a Response), Kata runs it through the route's output schema before serialising — a last check that the server is actually sending the shape it promised. What happens on a mismatch is deliberately configurable, because the right reaction differs by environment; it is set by the app's outputValidation mode (ADR-0009):
| Mode | On mismatch | Intended environment |
|---|---|---|
strict | Log the issues, return 500 internal_output_shape_mismatch | dev / test / CI |
log | Log the issues, send the handler's data through unchanged | production |
off | Skip output validation entirely | perf-critical opt-out |
The three modes trace the tension between catching bugs and staying up: strict fails loudly, so a wrong shape can never slip past in dev or CI; log keeps production serving, letting a benign drift become a log line instead of an outage; off removes the check entirely where every microsecond counts.
The mode is resolved once at createApp, first match wins:
- the explicit
outputValidationpassed tocreateApp, - the
KATA_OUTPUT_VALIDATIONenv var when it names a valid mode, - derived from
NODE_ENV—production→log, otherwisestrict.
const app = createApp({ modules: [users], outputValidation: 'strict' })In strict mode the Zod issues are logged server-side (through your injected logger if one is registered, else console.error) and the response is exactly:
{ "error": "internal_output_shape_mismatch", "message": "Response did not match the declared output schema" }with status 500. This catches "the handler returned almost the right shape" before it reaches a client. In log mode the issues are still logged, but the handler's data is sent through unchanged — a benign shape drift in production degrades to a log line instead of a hard 500. In off mode there is no safeParse and no Zod transform; the data passes through as-is.
The mismatch is never leaked to the client
On a strict mismatch the client receives the generic internal_output_shape_mismatch envelope. The offending Zod issues are logged server-side only — field names and internal shape never cross the wire.
Uncaught throws: internal_error
A throw that escapes any middleware or handler is caught by Kata's global error boundary and serialised through the same envelope:
{ "error": "internal_error", "message": "Internal server error" }with status 500 and Content-Type: application/json — never Hono's default text/HTML 500 page. That boundary exists so a bug can never leak a stack trace or an HTML error page to a client: the raw error is logged server-side, and the underlying message is never surfaced.
The error handed to your logger.error arrives pre-flattened, not as a raw Error: { err: { name, message, stack?, cause?, errors? } }, with cause chains walked (depth-capped, cycle-safe) and AggregateError.errors expanded. A raw Error serialises to "{}" under the naive JSON.stringify-based logger most structured loggers start as — its message and stack are non-enumerable — so Kata never hands one to your logger directly.
Reserve throwing for genuine bugs. For failures the client should understand, return c.error(...).
Testing this without a crash route
Exercising this path needs a route that always throws — but that route should never ship on the app's real surface (a GET /diagnostics/boom reachable in production). Testing the error boundary without a crash route shows the pattern: build the throwing route inside the test file, with the app's own createApp/defineRoute, and never add it to main.ts's modules array.
Custom statuses: c.error and c.json
For domain errors — not found, forbidden, conflict — return a Response from the handler. The idiomatic way is c.error(code, message, extra?), which builds the unified envelope; c.json(value, status?) is the escape hatch for a custom shape. Both are available on the route and middleware contexts.
return c.error('not_found', 'No user with that id', { status: 404 })
// → 404 { "error": "not_found", "message": "No user with that id" }c.error's signature:
c.error(code: string, message: string, extra?: ErrorExtra): Response
type ErrorExtra = {
status?: number // defaults to 400
issues?: Record<string, FieldIssue[]> // attach structured field errors
}- The
codeargument becomes the wireerrorfield. statusrides insideextraand defaults to400.- Attach structured field errors via
extra.issues(the sameFieldIssue[]shape as the 422 envelope).
The distinction that governs the response pipeline (the same one from Routes & schemas):
- return a value → validated against
output, sent as200. - return
c.error(...)/c.json(body, status)→ carries its own status.
Returned responses and the output schema
With a single output schema, a returned Response (including c.error) short-circuits the route and is not checked against it — which is precisely why an error body is allowed to differ from your success shape.
export const getUserRoute = defineRoute({
method: 'GET',
path: '/users/:id',
input: { params: z.object({ id: z.string() }) },
output: UserSchema,
handler: async (c) => {
const user = await getUser(c.input.params.id)
if (!user) return c.error('not_found', 'User not found', { status: 404 }) // not validated
return user // validated against UserSchema
},
})To type and validate error bodies too, declare output as a status→schema map (ADR-0011). Kata ships ErrorBodySchema for exactly this — the Zod mirror of the unified envelope:
import { ErrorBodySchema } from '@katajs-framework/core'
export const getUserRoute = defineRoute({
method: 'GET',
path: '/users/:id',
input: { params: GetUserParamsSchema },
output: { 200: UserSchema, 404: ErrorBodySchema },
handler: async (c) => {
const user = await getUser(c.input.params.id)
if (!user) return c.error('not_found', 'User not found', { status: 404 })
return user
},
})In the map form: a plain return is the 200 body; c.json(body, 201) is validated against output[201]; a c.error(...) whose status is declared is validated against that status's schema. Undeclared statuses still pass through unvalidated. The original Response is forwarded verbatim on success — Kata never re-serialises a response your handler built, so a header or content type you set is preserved. The RPC client narrows by status: InferResponseType<call, 404>. See defineRoute for the full output contract.
The wrong schema behind an error status silently breaks that error
Declaring a status opts it into validation, and c.error(...) always emits the unified { error, message } envelope. So if the schema under a 4xx key is anything else — the success DTO, copied one line up by accident — the envelope fails its own declared schema, and what the caller gets depends on the mode rather than on your handler:
output: { 200: TodoSchema, 400: TodoSchema } // ← 400 is not the envelope
handler: (c) => c.error('invalid_filter', 'Unknown filter', { status: 400 }),strict(the default outside production) — your400is replaced by500 { "error": "internal_output_shape_mismatch", … }. The domain error never reaches the caller.log(the default in production) — the malformed400ships to the caller as written, and only a server-side log line records the mismatch.
Neither mode is the behaviour you wanted, and the one that hides it is the one production runs. Put ErrorBodySchema — or a refinement of it — behind every declared 4xx/5xx, and the mismatch becomes a compile-time concern instead of a runtime one.
What's automatic vs. what you write
| Situation | Status | Who produces it |
|---|---|---|
| No route matches the path | 404 | Kata (automatic) |
| Path matches, method doesn't | 405 | Kata (automatic) |
| Input fails its schema | 422 | Kata (automatic) |
Handler returns a value matching output | 200 | Kata |
Handler returns c.error(...) / c.json(body, status) | your status | you |
Handler return value fails output | 500 (mode-dependent) | Kata (automatic) |
| Handler throws | 500 | Kata's error boundary |
Gotchas
- A malformed JSON body returns
400validation_failed(message: "Malformed JSON body") before schema validation — the unparseable bytes never reach yourbodyschema. An empty or absent body is different: it reads asundefined, so thebodyschema decides (an optional body passes; a required one →422). - Every response carries a correlation id. Success or error, Kata echoes an
X-Request-Idheader (reusing a well-formed inbound one, otherwise a fresh UUID). See Lifecycle. statusis not a positional argument onc.error. It lives insideextraand defaults to400—c.error('not_found', '…')without a status returns400, not404.
See also
defineRoute— theinput/outputcontract.- Errors cookbook — worked recipes for returning your own 4xx.