backend-error-handling

Backend Error Handling - No try/catch

Backend errors are handled centrally by apps/backend/src/middleware/error/error-middleware.ts.

NEVER wrap logic in try/catch blocks. This is the single most important backend rule. The centralized error middleware handles all error formatting, logging, HTTP responses, and Sentry reporting. Local try/catch blocks hide bugs, create inconsistent error responses, and — most critically — bypass Sentry, destroying error visibility. Every swallowed error is an error we never see in production.

Why this matters

The error middleware decides:

• What gets logged locally (all errors).
• What gets reported to Sentry (unexpected/infrastructure errors).
• What gets returned to the client (typed error responses with correct status codes).

When you catch and swallow an error, none of that happens. The error is invisible.

Rules

• Do NOT use try/catch in routes, features, modules, queries, mutations, or any backend logic.
• Throw typed errors from @backend/middleware/error and let errorMiddleware format the response.
• Prefer ApplicationError, AuthError, AuthorizationError, or ValidationError with the matching error code enum.
• Let Zod, Hono validator, database, Resend, and unexpected errors bubble up.
• Do not duplicate centralized behavior with catch (error) { return c.json(...) } or catch (error) { logger.error(...) }.
• Do not swallow errors with empty catch blocks or catch-and-log patterns.

Exceptions (must justify)

Only these patterns are acceptable:

1. Cleanup with rethrow — catch block does local cleanup (delete temp file, remove cookie) then rethrows. The catch block must rethrow.

2. Third-party business logic — When a third-party SDK error IS the expected business logic (e.g., auth email_verification_required during signup, session auth returning failure for WebSocket upgrades). In these cases the error is a data signal, not a failure. Use .catch(() => null) or check error codes and rethrow for anything unexpected.