Error Pages

Custom error handling for production mode with support for branded error pages.

Production-Ready Error Pages

Soli provides detailed error pages during development and clean, user-friendly pages in production. You can customize error pages to match your brand.

1 Development vs Production Mode

Development Mode

Full stack traces
Interactive REPL for debugging
Request details (params, body, headers)
Source code preview

soli serve

Production Mode

Clean, branded error pages
No stack traces or internal details
Error ID for support reference
Customizable templates

soli serve --no-dev

2 Default Error Pages

Soli includes built-in error pages for common HTTP status codes:

Status	Description
400	Bad Request
403	Forbidden
404	Not Found
405	Method Not Allowed
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable

3 Custom Error Pages

Create custom error pages by placing templates in app/views/errors/.

Directory Structure

app/
  views/
    errors/
      400.html.slv    # Custom 400 Bad Request page
      403.html.slv    # Custom 403 Forbidden page
      404.html.slv    # Custom 404 Not Found page
      500.html.slv    # Custom 500 Internal Server Error page
      502.html.slv    # Custom 502 Bad Gateway page
      503.html.slv    # Custom 503 Service Unavailable page

Template Variables

Variable	Type	Description
status	Number	HTTP status code (e.g., 500)
message	String	Error message
request_id	String	Unique identifier for support

Example: Custom 404 Page

<div style="min-height: 100vh; display: flex; align-items: center; justify-content: center; background-color: #f8f9fa;">
    <div style="text-align: center;">
        <h1 style="font-size: 6rem; font-weight: bold; color: #343a40; margin-bottom: 1rem;"><%= status %></h1>
        <h2 style="font-size: 1.5rem; font-weight: 600; color: #6c757d; margin-bottom: 1rem;">Page Not Found</h2>
        <p style="color: #6c757d; margin-bottom: 2rem;"><%= message %></p>
        <a href="/" style="display: inline-block; padding: 0.75rem 1.5rem; background-color: #007bff; color: white; border-radius: 0.375rem;">Go Home</a>
        <p style="margin-top: 2rem; font-size: 0.75rem; color: #adb5bd;">Error ID: <%= request_id %></p>
    </div>
</div>

Example: Custom 500 Page

<div style="min-height: 100vh; display: flex; align-items: center; justify-content: center; background-color: #fff5f5;">
    <div style="text-align: center; max-width: 400px;">
        <h1 style="font-size: 3rem; font-weight: bold; color: #c53030; margin-bottom: 1rem;"><%= status %></h1>
        <h2 style="font-size: 1.25rem; font-weight: 600; color: #1a202c; margin-bottom: 1rem;">Something went wrong</h2>
        <p style="color: #4a5568; margin-bottom: 2rem;">We're sorry, but something unexpected happened.</p>
        <a href="/" style="display: inline-block; padding: 0.75rem 1.5rem; background-color: #c53030; color: white; border-radius: 0.375rem;">Return to Homepage</a>
        <p style="margin-top: 2rem; font-size: 0.75rem; color: #718096;">Reference ID: <%= request_id %></p>
    </div>
</div>

Using Tailwind CSS

If your application already uses Tailwind CSS, you can use Tailwind classes instead of inline styles for cleaner templates.

4 Important Notes

No Layouts
Error pages render without application layouts to avoid potential cascading errors.
Optional
Custom error pages are optional. If a template doesn't exist, Soli uses the default error page.
Full Template Features
Error templates support all template features including conditionals, loops, and partials.

5 Production Deployment

# Using soli CLI
soli serve --no-dev

# Or set environment variable
SOLI_ENV=production soli serve

Production Mode Ensures:

Custom error pages are used
No sensitive information is leaked
Error IDs are generated for support reference

Best Practices

Keep it Simple

Error pages should be clean and focused on helping users return to working pages.

Provide Navigation

Include links to help users return to working pages (home, back, etc.).

Log Error IDs

Store error IDs in your logs to correlate user reports with server errors.

Test Error Flows

Regularly test custom error pages to ensure they render correctly.