tarampampam/error-pages

[!IMPORTANT] If you were on v3 or earlier and want to upgrade to v4, check out the migration guide.

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

[!NOTE] The cats template is the only one of those that fetches resources (the actual cat pictures) from external servers - all other templates are self-contained.

[!TIP] If you need the pre-rendered static error pages pack, you can download it as a zip or tar.gz archive.

🚀 Installation

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

Registry	Image
GitHub Container Registry	ghcr.io/tarampampam/error-pages
Quay.io (mirror)	quay.io/tarampampam/error-pages
Docker Hub (mirror)	tarampampam/error-pages

[!WARNING] Using the latest tag for Docker images is strongly discouraged, as it may introduce backward-incompatible changes during major upgrades. Use versioned tags in the X, X.Y, or X.Y.Z format instead.

[!IMPORTANT] The app is distributed as two separate binaries - error-pages (HTTP server) and builder. Docker tags follow this convention:

• X.Y.Z (and X.Y, X) - includes the HTTP server
• X.Y.Z-builder (and X.Y-builder, X-builder) - includes the builder and a pre-rendered error pages pack

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.

Helm chart sources are located in the deploy/helm directory of the repository.

🛠 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):

Format	p50 (typical response time)	p90 (90% of responses complete within this time)
HTML	121 µs	262 µs
JSON	51 µs	75 µs
XML	48 µs	73 µs
Plain text	47 µs	68 µs
HTML + gzip	2.4 ms	3.1 ms
JSON + gzip	256 µs	510 µs

[!NOTE] HTML responses are large (full rendered template, ~65 KB), which is why gzip compression takes noticeably more time there. JSON/XML/text are compact structured responses, so they are fastest overall.

💻 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:

Path	Description
/healthz, /health, /health/live, /live	Liveness probe - always returns 200 OK
/version	Returns {"version":"..."} as JSON

Response headers

Every error page response includes the following headers automatically:

Header	Value	Notes
Content-Type	e.g. text/html; charset=utf-8	Format-dependent
Content-Length	Response body size in bytes	Always set
X-Robots-Tag	noindex, nofollow, nosnippet, noarchive	Prevents error pages from being indexed
Retry-After	120	Only for limited set of status codes
Content-Encoding	gzip	Only when the client sends Accept-Encoding: gzip

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.