donlon/cloudflare-error-page: Rendering Fake Cloudflare Error Pages from Python and Node
✅Browser ❌Cloudflare ✅Host — Generator for customized Cloudflare error pages. (unofficial)
At a glance
- What is it?
- An unofficial generator that reproduces the Cloudflare error page in HTML, with Python and JavaScript packages plus a browser editor. Useful for demos and jokes, awkward for anything that has to be honest with users.
- Who is it for?
- Adopt it if you need a convincing Cloudflare error page for a demo, a teaching example, or an internal joke, and you are comfortable that the project's own FAQ tells you to use it at your own risk. Do not adopt it as the error page real users see during an outage: a page that imitates Cloudflare while your own server is down is the exact scenario the README warns about, and it delays the one signal users need.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 132 days ago.
- What is it written in?
- Mainly HTML, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- donlon/cloudflare-error-page5,792 ★ · +57
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| donlon/cloudflare-error-page | 5.7k | 5.8k |
57 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What the Cloudflare Error Page Generator Is Actually For
The README states the goal plainly: the project creates customized error pages that mimic the well-known Cloudflare error page, and you can embed it into your own website. That is a narrow job. It is not a status page, not an incident tool, and not a way to intercept real Cloudflare errors, because Cloudflare serves those from its own edge before your code runs.
The audience is developers who need a Cloudflare-looking page on purpose. Three cases show up in the repository's own examples: a demo server that renders the page live, a joke page that claims the web server is working while showing a 200, and a deliberately over-the-top catastrophic infrastructure failure page. The editor at magicalforest.io/cferr/editor/ exists for people who want to build one without writing code.
One detail in the repository metadata matters for expectations. The pyproject.toml classifier is Development Status :: 4 - Beta. The last push to the default branch was on 2026-07-06, so the code has moved recently, but the project labels itself beta and the README does not document a versioning or deprecation policy. Treat the parameter names as the interface and expect them to be the thing that changes.
How the Renderer Builds a Page from a Parameter Dictionary
Both language bindings expose a single function named render, and both take one dictionary of parameters. The Python package is a Jinja2 template engine wrapper: pyproject.toml lists jinja2>=3.0 as the only runtime dependency, and the wheel build uses a custom hatch hook at scripts/hatch_build.py. The Node package exposes the same render entry point, imported in the README example as render renamed to render_cf_error_page.
The parameter dictionary is where the architecture of the page lives. Three nested objects, browser_status, cloudflare_status and host_status, each carry a status field and an optional status_text and location. A separate error_source key picks which of the three gets the error indicator, and the README says valid options are 'browser', 'cloudflare', and 'host'. The top-level keys html_title, title, error_code, time, what_happened and what_can_i_do fill in the rest of the chrome. The what_happened and what_can_i_do values accept HTML, which is how the examples pass paragraph tags.
Two keys exist specifically to make the output look real. ray_id and client_ip fill the Ray ID and user IP fields. The README points at the Cf-Ray request header, formatted like Cf-Ray: 230b030023ae2822-SJC, as the source for both the Ray ID and the three-letter data center code, and links a separate colo list repository for turning that code into a city name. The demo server's own handling of this is in editor/server/utils.py, per the README. Nothing in the renderer fetches that header for you. You pass it in.
Installing cloudflare-error-page and Rendering Your First Page
The Python package installs from PyPI and requires Python 3.10 or newer, per the requires-python field in pyproject.toml. The README gives the pip command directly.
pip install cloudflare-error-pageThe README's Python example imports the render function under an alias and passes a parameter dictionary. The block below is that example, with the parameter values kept exactly as the README shows them.
import webbrowser
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',
},
'error_source': 'cloudflare',
})The return value is a complete HTML document as a string. If you leave time empty, the README says the current UTC time is shown.
For a Node service, the package installs from npm and the README shows it wired into an Express error handler, where the render result is sent with res.status(500). The README also ships examples/flask_demo.py for a Python server and links a live demo of the default page, so you can compare your output against a known-good render before changing anything.
The Trademark Question the README Answers Honestly
The project's FAQ does not pretend the legal position is clean. Asked whether putting this on your website is legal, given that it contains a trademarked logo and name and pretends to be official, the README answers: use it at your own risk, and notes there are still chances Cloudflare sends a takedown request or takes legal action. It adds that this depends on whether you use it properly, and suggests changing the texts on the page so users know it is a joke.
The README then goes further than most projects would. It says that if you do want to use a Cloudflare-pretending error page in production, you should fix your server quickly when it goes down so they will not find that you are faking their error page. That is the maintainer telling you the production use case is a bad idea, in the documentation, with a link to issue #4.
That is a real limitation, not a hypothetical one. The failure mode is not that the renderer breaks. It is that the page works exactly as intended while your users are misled about who is at fault. The MIT licence on the code does not grant anything with respect to Cloudflare's marks, and the README's own wording is a warning rather than a permission. I would read the FAQ as the project's position on scope: demos and jokes, with the disclaimer text edited in.
Where a Plain Error Page or a Status Page Fits Better
The obvious alternative is not another generator. It is a plain, honest error page: your own 500 template, no borrowed branding, that says the service is down and nothing more. That costs one template file and removes the entire trademark question. The Cloudflare generator wins only when the imitation is the point.
If the goal is keeping users informed during incidents, a hosted status page is the different tool. It lives on separate infrastructure, so it stays up when your app does not, which is precisely the property an error page rendered by your own failing server cannot have. The generator's render call runs inside the process that just threw, so it is unavailable in exactly the outages where a status page earns its keep.
The README's See also section names one closer comparison: oftx/cloudflare-error-page, described as a React reimplementation of the original page that can be deployed directly to Cloudflare Pages. That is a different deployment model. The React version compiles to static assets you host on a CDN, so it survives your origin going down, while donlon/cloudflare-error-page renders server-side from a parameter dictionary at request time. If you want the page to outlive the server, the static route is the one that does it. The README also links cloudflare-error-page-3th.pages.dev, which shows an error page for every HTTP status code and randomizes on reload.
Maintenance, Packaging Signals and What to Verify Before Upgrading
The repository is not archived, and the last push was on 2026-07-06. The repository has no published releases. So the upgrade story is: pin a version, read the diff, re-render your pages, and compare against the live demos the README links. There is no migration guide to lean on.
Packaging is the part with the most visible structure. The Python side builds with hatchling, pulls its version dynamically from cloudflare_error_page/__init__.py, and ships resources/**/* and scripts/**/* in the source distribution. That means the Jinja2 templates and the build script are part of the sdist, which is worth knowing if you vendor the package or audit what gets installed. The only declared runtime dependency is jinja2>=3.0, so the dependency surface is small. Ruff is configured with a 120-character line length and targets py310.
Licence terms are MIT for the code, stated in pyproject.toml and present as LICENSE.txt at the repository root. That covers the source. It says nothing about the Cloudflare name, logo, or the visual design the templates reproduce, and the README's FAQ is the project's own acknowledgement of that gap. I am not a lawyer and this is not legal advice, but the distinction between the code licence and the marks is the one that decides whether your use is defensible.
Editorial conclusion
Adopt it if you need a convincing Cloudflare error page for a demo, a teaching example, or an internal joke, and you are comfortable that the project's own FAQ tells you to use it at your own risk. Do not adopt it as the error page real users see during an outage: a page that imitates Cloudflare while your own server is down is the exact scenario the README warns about, and it delays the one signal users need. Before shipping anything, verify two things in the render output: that ray_id is populated from the Cf-Ray request header and client_ip is set rather than left blank, and that the bottom texts you pass in what_happened and what_can_i_do make clear the page is not official. If you cannot make that second one true, the online editor at magicalforest.io/cferr/editor/ is where this project should stay.
Frequently asked questions
Does donlon/cloudflare-error-page render a real Cloudflare error?
No. It generates an HTML page that mimics the Cloudflare error page, and the README describes it as unofficial. Real Cloudflare errors are served by Cloudflare's edge, not by this renderer.
How do I make the generated page show a realistic Ray ID and user IP?
Pass the ray_id and client_ip properties in the params dictionary given to the render function. The README says the real values come from the Cf-Ray request header, for example Cf-Ray: 230b030023ae2822-SJC, and links a separate colo list for mapping the three-letter code to a city.
Which Python version does cloudflare-error-page need?
The requires-python field in pyproject.toml is >=3.10, and the classifiers list 3.10 through 3.14 on CPython and PyPy. The only runtime dependency declared is jinja2>=3.0.
Is putting a fake Cloudflare error page on my website legal?
The README answers this directly: use it at your own risk, and it notes there are still chances Cloudflare sends a takedown request or takes legal action. It suggests changing the page texts so users know it is a joke.
Can I build a Cloudflare-style error page without writing code?
Yes. The README links an online editor at magicalforest.io/cferr/editor/ for creating customized error pages and example server apps, alongside the Python and JavaScript packages.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/donlon-cloudflare-error-page)Star history chart for your README
[](https://hysenlabs.com/projects/donlon-cloudflare-error-page)Was this useful?