tarampampam/error-pages repository overview

⁠

If you ended up here, chances are you would like to replace your HTTP server's default error pages with something more original and eye-catching. That is exactly what this project is designed for - it handles this with minimal effort on your part.

It includes:

• A collection of HTTP error page designs (each with a unique look), along with the ability to use your own custom templates
• A lightweight HTTP server for serving these pages that integrates easily into your existing infrastructure
• A utility for pre-rendering static HTTP error pages

Key features:

• Both the HTTP server and the static generator are written in Go with zero third-party runtime dependencies (stdlib only - hardcore mode)
  • Supports HTTP/1.1 and HTTP/2 (h2c - cleartext, no TLS required)
  • Returns error responses in the appropriate format (HTML, JSON, XML, plain text) based on client requests
  • Gzip compression for all response formats
  • HTML pages support localization (15+ languages), responsive design (mobile-friendly), and are fully self-contained - all styles and images are embedded directly in the HTML, without loading any external resources
  • Go template-based templating engine
• Ships as pre-built binaries, a minimal Docker image (rootless, scratch-based), and a ready-to-use Helm chart for Kubernetes
• Works out of the box with popular reverse proxies and ingress controllers (Nginx, Traefik, etc.)

⁠🪂 Built-in templates

The following templates are built-in and available for use without any additional setup/files:

Template name	Preview (light)	Preview (dark)
app-down
cats
connection
ghost
hacker-terminal
l7
lost-in-space
noise
orient
shuffle
win98

⁠🚀 Installation

Download the latest binary for your OS/architecture from the releases page⁠, or use the Docker image:

Supported image architectures - linux/amd64, linux/arm/v7, linux/arm64, linux/ppc64le, linux/s390x. All images are signed with Cosign⁠ using keyless signing (GitHub OIDC).

⁠📦 Helm chart

A Helm chart for Kubernetes is included with each release (download⁠), published on Artifact Hub⁠, and also available via an OCI registry (Helm v3.8+ required):

helm install error-pages \
  oci://ghcr.io/tarampampam/error-pages/charts/error-pages \
  --version X.Y.Z

All supported chart values, examples, and usage instructions can be found at Artifact Hub⁠.

⁠🛠 Integration guides

• Standalone server or builder usage:

  • 🚀 Start the HTTP server with a custom template (theme)⁠
  • 🚀 Generate error pages using built-in or custom templates⁠

• With Nginx:

  • 🚀 Customize error pages in your own Nginx Docker image⁠
  • 🚀 Use Nginx as a reverse proxy with custom error pages⁠

• With Caddy:

  • 🚀 Customize error pages in your own Caddy Docker image⁠
  • 🚀 Use Caddy as a reverse proxy with custom error pages⁠

• With Traefik:

  • 🚀 Use Traefik with a local Docker Compose setup⁠

• With Kubernetes:

  • 🚀 Use error-pages as the ingress-nginx default backend⁠
  • 🚀 Use error-pages with Traefik in Kubernetes⁠
  • 🚀 Use error-pages with NGINX Gateway Fabric in Kubernetes⁠
  • 🚀 Use error-pages with Envoy Gateway in Kubernetes⁠
  • 🚀 Use error pages with HAProxy Ingress in Kubernetes⁠

⁠🦾 Performance

Measured on loopback (127.0.0.1), single connection, no artificial load (wrk -t1 -c1 -d5s --latency http://127.0.0.1:8080/..., less is better):

⁠💻 Command-line usage

For detailed instructions on using the HTTP server and the static site generator, including all supported environment variables and usage examples, check the CLI documentation⁠.

⁠🔍 How the server handles requests

The three most important things to understand about how the server behaves - how it determines which error page to show, which format to return, and what request context it can expose.

⁠How the error code is resolved

The server picks the HTTP status code from the first matching source:

1. Path: /404, /404.html, /404.json, /503.xml, etc.
2. X-Code request header
3. Default: --default-error-page (or DEFAULT_ERROR_PAGE, default: 404)

⁠How the response format is determined

The response format is picked from the first matching source:

1. Path extension: .html, .htm, .json, .xml, .txt
2. Content-Type request header
3. X-Format request header (e.g. X-Format: application/json)
4. Accept request header
5. Default: plain text

Supported formats: HTML, JSON, XML, plain text.

⁠Service endpoints

The following HTTP endpoints can be used for health checks, monitoring, or other purposes:

⁠Response headers

Every error page response includes the following headers automatically:

Headers listed in --proxy-headers (default: X-Request-Id, X-Trace-Id, X-Correlation-Id, X-Amzn-Trace-Id) are copied from the incoming request to the response when present.

⁠HTTP status code of the response

By default, the server always responds with HTTP 200, even when rendering error pages. This is the correct behavior when a reverse proxy (Nginx, Traefik, ingress-nginx) intercepts upstream error responses and replaces only the body - the proxy itself sends the original error status code back to the client.

When error-pages is used as a direct backend - e.g. a catch-all route, a Kubernetes default backend, or standalone testing - it must return the correct status code itself. Enable --send-same-http-code (or env SEND_SAME_HTTP_CODE=true) to make the HTTP response status match the error code being rendered.

⁠📝 Templating and Localization

For detailed instructions on using custom templates and localization features, see the templating documentation⁠.

⁠🔧 Development

⁠Requirements

• Go 1.27+⁠ for building from source and running tests
• Optional: golangci-lint⁠ for linting
• Optional: docker⁠ for testing the Docker image locally
• Optional: helm⁠ + kind⁠ + docker for testing the Helm chart locally in Kubernetes
• Optional: helm-docs⁠ for generating Helm chart documentation
• Optional: wrk⁠ for benchmarking the server performance
• Optional: watchexec⁠ for live reloading the server during development

Commands:

go generate -skip readme ./...            # (re)generate code, except docs
go generate ./...                         # (re)generate everything
go build ./cmd/error-pages/ && go build ./cmd/builder/ # build both binaries
go test -race ./...                       # run all tests
golangci-lint run --fix                   # lint the code and apply any available auto fixes
helm-docs -c ./deploy/helm/ -t README.tpl.md -o README.md # regenerate chart readme file

# run a live reloading server (useful for testing template changes)
watchexec -r -- go run ./cmd/error-pages/ --show-details

⁠🧑‍🤝‍🧑 Contributors

I want to say a big thank you to everyone who contributed to this project:

⁠👾 Support

If you encounter any bugs in the project, please create an issue⁠ in this repository.

⁠📖 License

This is open-sourced software licensed under the MIT License⁠.