stacks-error-handling

name	stacks-error-handling
description	Use when implementing error handling in Stacks — the Result type (Ok/Err), handleError function, error page rendering (development with stack traces, production with friendly messages), ErrorHandler class, ModelNotFoundException, HTTP error mapping, log file writing, or error configuration. Covers @stacksjs/error-handling and config/errors.ts.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Stacks Error Handling

Type-safe error handling with Result types, error pages, and structured logging.

Key Paths

• Core package: storage/framework/core/error-handling/src/
• Configuration: config/errors.ts
• Error model: storage/framework/defaults/app/Models/Error.ts

Result Type (from ts-error-handling)

import { ok, err, fromPromise } from '@stacksjs/error-handling'
import type { Result, Ok, Err, ResultAsync } from '@stacksjs/error-handling'

// Create results
const success: Ok<string> = ok('data')
const failure: Err<Error> = err(new Error('failed'))

// From promises
const result: ResultAsync<Data, Error> = fromPromise(fetchData())

// Pattern matching
if (result.isOk()) {
  console.log(result.value)
} else {
  console.error(result.error)
}

Error Handler

import { handleError, ErrorHandler } from '@stacksjs/error-handling'

// Function-based
handleError(error)
handleError(error, { shouldExit: true })

// Class-based
ErrorHandler.handle(error)
ErrorHandler.handleError(error, { shouldExit: true })
ErrorHandler.writeErrorToFile(error)
ErrorHandler.writeErrorToConsole(error)

Log File Writing

import { writeToLogFile, setLogPath } from '@stacksjs/error-handling'

setLogPath('/custom/log/path')
await writeToLogFile('Error message', { path: '/custom/path' })

Default log path: storage/logs/stacks.log

Error Page Rendering

import { ErrorPageHandler, renderError, renderErrorPage, renderProductionErrorPage, createErrorHandler, errorResponse } from '@stacksjs/error-handling'

// Development: shows stack trace, source code, file paths
const devPage = renderErrorPage(error, request)

// Production: friendly error message, no internals
const prodPage = renderProductionErrorPage(error, request)

// Auto-detect environment
const page = renderError(error, request)

// Create handler for routes
const handler = createErrorHandler()
const response = errorResponse(error, request)

HTTP Error Mapping

import { HTTP_ERRORS } from '@stacksjs/error-handling'

// Maps status codes to error details
HTTP_ERRORS[400]  // { title: 'Bad Request', ... }
HTTP_ERRORS[401]  // { title: 'Unauthorized', ... }
HTTP_ERRORS[403]  // { title: 'Forbidden', ... }
HTTP_ERRORS[404]  // { title: 'Not Found', ... }
HTTP_ERRORS[500]  // { title: 'Internal Server Error', ... }

Custom Exceptions

import { ModelNotFoundException } from '@stacksjs/error-handling'

throw new ModelNotFoundException('User not found')

Error Page Types

interface HttpError { status: number, title: string, message: string }
interface StackFrame { file: string, line: number, column: number, function?: string }
interface CodeSnippet { line: number, code: string, isHighlighted: boolean }

Error Model (storage/framework/defaults/app/Models/Error.ts)

Fields: type, message, stack (stacktrace), status, additional_info Seeder: 10 records for testing

config/errors.ts

Contains comprehensive validation error messages for all field types:

• String validation: required, minLength, maxLength, email, url, uuid, etc.
• Number validation: required, min, max, positive, negative, integer, etc.
• Enum validation: invalid value messages
• Date validation: format, before, after, etc.
• File validation: size, type, dimensions, etc.

Gotchas

• Use Result<T, E> types instead of try/catch for recoverable errors
• ok() and err() are from ts-error-handling (neverthrow-compatible)
• Error pages automatically detect environment (dev shows stack traces, prod doesn't)
• handleError() logs to both console and file
• ModelNotFoundException is thrown by findOrFail() and firstOrFail() ORM methods
• The Error model persists errors to the database for tracking
• config/errors.ts is a comprehensive i18n-ready error message catalog
• ErrorHandler.isTestEnvironment prevents process exit during tests
• ERROR_PAGE_CSS contains built-in styling for error pages