Skills / Conventions

error-handling-conventions

Handles errors with cause chains, typed results, one API error envelope, no log-and-throw and no empty catch.

Group

Conventions

Kind

Read-only

Loads when

Writing or reviewing error handling in TypeScript

When it runs

When error handling is being written or reviewed in TypeScript files. Claude loads it on its own when the description matches the file or the task; it never writes anything itself. It matches:

• TypeScript files
• error handling
• API error responses

The conventions

• Keep the cause chain. Rethrow with cause rather than replacing the original error with a bare throw new Error(msg).
• Return an explicit result. A function that can fail returns a typed result or union, or throws. Never untyped null or undefined as the failure signal.
• One API error envelope. The machine code is SCREAMING_SNAKE_CASE, the message is for humans, and a stack trace never reaches the client.
• Do not log and throw. Either handle and log an error, or propagate it. Both at once means duplicate logs and false alerts.
• No empty catch. Swallowing an error needs a directive comment explaining why it is correct, and it almost never is.
• Exceptions are not control flow. An expected missing record is a typed result, not a try/catch around the happy path.

throw new AppError("...", { cause: err })

{ok:true,data}|{ok:false,error}

{ error: { code, message, details? } }

Related

• nextjs-conventions returns this envelope from Server Actions.
• project-baseline probes for safe error responses.
• defensive-coding-conventions: defect classes on error paths.