cloudflare-error-page: A Generator for Customised Cloudflare-Style Error Pages

What the Package Generates and Why Developers Use It

When a server behind Cloudflare goes down, users see the familiar Cloudflare error page with three status indicators: Browser, Cloudflare, and Host. Each shows either a check or an error, and the combination tells the user where the failure is. cloudflare-error-page generates HTML that matches this layout exactly, including the three-panel status display, a customisable title, error code, timestamp, Ray ID field, and a 'what happened' explanation block. Developers use it for two main scenarios: replacing the default server error page with something that looks consistent with Cloudflare's design, and building UI tests or demos that need a realistic error page without relying on a live failure. The online editor at magicalforest.io/cferr/editor/ lets anyone configure and preview a page in the browser before writing a single line of code. Live demos at magicalforest.io/cferr/examples/ cover a default layout, a catastrophic failure scenario where all three indicators show error, and a working-server page where all three show ok, giving a quick sense of the visual range the package supports.

Installing and Using the Python Package

Install the Python package from PyPI:

pip install cloudflare-error-page

The package requires Python 3.10 or later and depends on jinja2 3.0 or higher. Rendering a page calls the `render` function with a dictionary of parameters:

from cloudflare_error_page import render as render_cf_error_page

error_page = render_cf_error_page({
    'browser_status': {
        "status": 'ok',
    },
    'cloudflare_status': {
        "status": 'error',
        "status_text": 'Error',
    },
    'host_status': {
        "status": 'ok',
        "location": 'example.com',
    },
})

The function returns an HTML string. The README includes a Flask demo in `examples/flask_demo.py` that shows how to wire this into a web framework's error handler.

Installing and Using the Node.js Package

The Node.js package installs via npm:

npm install cloudflare-error-page

The README shows an Express integration that intercepts unhandled errors and renders a 500 page:

import { render as render_cf_error_page } from 'cloudflare-error-page';

app.use((err, req, res) => {
  res.status(500).send(render_cf_error_page({
    "title": "Internal server error",
    "error_code": "500",
    "what_happened": err.toString(),
  }));
});

The Node.js implementation was created by a contributor credited as @junduck. The parameter names and structure are consistent between the Python and Node.js versions.

Embedding Real Cloudflare Ray IDs

A plain error page shows a placeholder Ray ID that does not match the real Cloudflare infrastructure. For a more realistic result, the package accepts `ray_id` and `client_ip` fields in the parameters dictionary. Cloudflare adds a `Cf-Ray` header to every proxied request in the format `Cf-Ray: 230b030023ae2822-SJC`. Extracting this header on the server and passing it to `ray_id` makes the error page show the actual Ray ID for the failed request. The three-letter airport code at the end of the header identifies the Cloudflare data centre; the README points to an external location list for mapping codes to city names. The demo server at magicalforest.io handles this extraction and serves as a reference implementation.

Full Parameter Reference and the Three-Panel Status Model

The README provides a complete parameter reference. The core fields are `title`, `error_code`, `html_title`, and `time` (defaults to current UTC if empty). The `more_information` block controls the 'Visit X for more information' footer, with options to hide it entirely or set a custom link. The three status panels are configured independently: `browser_status`, `cloudflare_status`, and `host_status` each take a `status` key set to either `ok` or `error`, optional `status_text`, and optional `location` for the host panel. The `error_source` field positions the error indicator arrow. The `what_happened` and `what_can_i_do` fields accept raw HTML strings, which means XSS risk if user-supplied content is passed without sanitisation. The `ray_id` and `client_ip` fields fill the corresponding display fields. The `time` field defaults to the current UTC time if left empty, which keeps the displayed timestamp accurate without requiring the caller to format a date string. The `error_source` field controls which of the three panels (browser, cloudflare, or host) shows the error arrow indicator, making it possible to direct the user's attention to the specific failure point rather than a generic error state.

Trademark Risk, Beta Status, and Appropriate Use

The README includes a direct legal warning: the package mimics Cloudflare's visual design and name, and there is a real risk that Cloudflare will issue a takedown request or take legal action if the page is used to impersonate their service. The README recommends changing the text so users know the page is not genuine, and specifically suggests fixing the server quickly if it goes down to avoid Cloudflare finding the fake page in production. The package is classified as `Development Status :: 4 - Beta` in pyproject.toml, which signals that the API may change between releases. The MIT licence on the package code does not confer any right to use Cloudflare's name or design in a way that constitutes trademark infringement; the licence covers only the generator code itself.

Comparison to Writing a Custom HTML Error Page

Writing a custom error page from scratch gives full control over the design and removes any trademark concern. The trade-off is time: reproducing the exact Cloudflare layout with the three-panel status display, the Ray ID field, and the correct typography requires either design work or copying HTML from a live page. cloudflare-error-page provides the layout as a tested, parameterised template built on jinja2, so the integration is a function call rather than HTML maintenance. For teams that want a completely original design, the package is unnecessary. For teams that specifically want the Cloudflare aesthetic and accept the trademark trade-off, the package reduces the implementation to a pip or npm install and a function call. The README also lists two related projects: cloudflare-error-page-3th.pages.dev, which shows an error page for every HTTP status code and reloads a random variant, and oftx/cloudflare-error-page, a React reimplementation that can be deployed directly to Cloudflare Pages. These two projects use the same visual language but are maintained separately and have different deployment targets.

Editorial conclusion

This package is a practical tool for developers who want their server error pages to match the visual style that users already recognise from Cloudflare, or who need to test UI flows that depend on a specific error page layout. It is not appropriate for use in a production environment without changing the text and branding, and the README is direct about the trademark risk: there is a real chance Cloudflare will issue a takedown request if the page is used to impersonate their service. The package is classified as Beta, so treat the API as potentially unstable. The Python build requires 3.10 or later and depends on jinja2. Verify the Ray ID injection logic by testing against a live Cloudflare-proxied request before deploying to a production error handler.

Frequently asked questions

Official sources

1. donlon/cloudflare-error-page on GitHub
2. Issues
3. License: MIT
4. Project website
5. README