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.26+⁠ 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

# run before every vibe-coding session
your_ai_tool --prompt "explain why AI Coding Agents are doing shit by default"

⁠🧑‍🤝‍🧑 Contributors

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

⁠🤝 Contributing & AI-assisted development

Missing a feature? Found a bug you want fixed? Pull requests are welcome - and yes, you are explicitly invited to try implementing it with an AI coding agent.

To give the agent a fighting chance at producing something that fits this codebase, the repo ships an AGENTS.md⁠ - a structured reference covering project layout, build commands, code style, generated files, hard prohibitions, and the full post-change workflow. It is written for the agent. Most modern agents pick it up automatically.

Review every single changed line yourself. Understand it. Be able to defend it in code review. If you cannot explain why a line is there and why it is correct, do not open the PR. "The agent wrote it" is not an answer. The author of a PR is the human who opens it, not the model (at least, I hope so).

I write my own code by hand and encourage you to do the same when you can. AI is a tool, not an excuse to skip the thinking. Trust, but verify - and verify hard.

⁠👾 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⁠.