Custom Error Pages

Custom Error Pages in Kamal allow developers to serve branded or specific HTML pages when the application proxy encounters 4xx or 5xx HTTP status codes. This feature ensures that users receive a polished experience even when the application is unreachable, in maintenance mode, or experiencing internal errors, rather than seeing a bare plaintext "Bad Gateway" or "Service Unavailable" message from the proxy.

The system works by identifying local HTML files, organizing them into versioned directories, and uploading them to the remote hosts where kamal-proxy can access them. This is particularly critical when using the intercept_errors proxy configuration, which discards the application's own error bodies in favor of these custom pages.

Sources: lib/kamal/configuration.rb:520-528, test/integration/app_test.rb:112-126

Architecture and Data Flow

The Custom Error Pages workflow involves a transition from local configuration to remote host deployment during the app:boot process.

Configuration Logic

Kamal checks the error_pages_path defined in the deployment configuration. If present, it validates that if intercept_errors is enabled on the proxy, these pages actually exist to prevent the proxy from falling back to plaintext status lines.

Sources: lib/kamal/configuration.rb:453-453, lib/kamal/configuration.rb:520-528

Deployment Sequence

When an application is booted, Kamal executes the following steps for error pages:

1. Local Preparation: Identifies files matching the glob {4??.html,5??.html} in the configured local path.
2. Temporary Staging: Copies matching files into a version-named sub-directory within a local temporary folder.
3. Remote Directory Creation: Commands are issued to the remote host to create the proxy's error page directory.
4. Upload: The staged files are uploaded to the remote host with specific permissions (0700).

Sources: lib/kamal/cli/app/error_pages.rb:16-37, lib/kamal/commands/app/error_pages.rb:3-5, lib/kamal/cli/app.rb:14-14

Visual Flow

The following diagram illustrates the lifecycle of error pages from local discovery to remote deployment.

Key Components

Command Generator

The Kamal::Commands::App::ErrorPages module defines the low-level shell commands required to manage the error page lifecycle on the remote server.

Sources: lib/kamal/commands/app/error_pages.rb:2-10

CLI Runner

The Kamal::Cli::App::ErrorPages class orchestrates the interaction between the local filesystem and the remote host via SSHKit.

Configuration Options

Custom error pages are primarily controlled via the deploy.yml configuration file.

Sources: lib/kamal/configuration.rb:453-453, lib/kamal/configuration.rb:520-528

Validation Rules

Kamal performs specific checks to ensure the reliability of the error page system:

• Presence Check: If intercept_errors is enabled for any role, error_pages_path must be configured. If missing, a warning is issued that the proxy will fall back to plaintext "Bad Gateway".
• Cleanup Policy: The system automatically cleans up directories that do not match the currently deployed version to prevent disk bloat.

Sources: lib/kamal/configuration.rb:520-528, lib/kamal/commands/app/error_pages.rb:7-9

Implementation Example

The following code demonstrates how Kamal creates the command to prune old error page directories:

# lib/kamal/commands/app/error_pages.rb:7-9
def clean_up_error_pages
  [ :find, config.proxy_boot.error_pages_directory, "-mindepth", "1", "-maxdepth", "1", "!", "-name", KAMAL.config.version, "-exec", "rm", "-rf", "{} +" ]
end

Sources: lib/kamal/commands/app/error_pages.rb:7-9

The integration tests verify that custom maintenance pages are served correctly during maintenance mode, confirming that the files are correctly placed for kamal-proxy to consume.

Sources: test/integration/app_test.rb:112-126

Custom Error Pages provide a critical layer of professional UI/UX by ensuring that infrastructure-level failures or planned maintenance are communicated to users via customized, branded templates rather than generic server errors. By versioning these pages alongside the application, Kamal ensures that the correct error branding is always available for the specific deployment version.