# umbraco-custom-error-pages

Sets up custom 404 and 500 error pages for Umbraco 16.1 and later, with a content-finder or config-based 404 option.

Skill by Umbraco. Category: Web and browsers.

## Install

Project (for this project only):

```sh
npx skills add umbraco/umbraco-cms-implementation-skills --skill umbraco-custom-error-pages
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add umbraco/umbraco-cms-implementation-skills --skill umbraco-custom-error-pages -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 3. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/umbraco/umbraco-cms-implementation-skills/umbraco-custom-error-pages)

## Source

[Open the source](https://github.com/umbraco/umbraco-cms-implementation-skills/tree/HEAD/plugins/implementation/skills/umbraco-custom-error-pages). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: umbraco-custom-error-pages
description: >
  Implement custom 404 and 500 error pages in Umbraco 16.1+. Offers two 404 approaches: a
  multi-site-aware IContentLastChanceFinder (default) and the official docs' zero-code
  Error404Collection config; 500s use a shared MVC controller. Trigger: user asks to "add
  custom error pages", "set up 404 page", "handle 500 errors", "create page not found",
  "implement error handling", "customize error pages in Umbraco". SKIP: non-Umbraco projects,
  and maintenance/upgrade pages (use umbraco-custom-maintenance-page instead).
---

# Custom Error Pages

Covers all three scenarios from the official tutorial: **404s have two supported approaches;
500s have exactly one** (unhandled exceptions bypass Umbraco's routing pipeline, so only a
plain MVC controller works — see
[500-error-controller.md](references/500-error-controller.md), shared by both approaches);
**Boot Failed has one trivial method** (see below).

Looking for a **maintenance page** (shown during Umbraco upgrades)? That's not an error page —
use the separate `umbraco-custom-maintenance-page` skill instead.

## Choose a 404 approach

| | **A — Content finder** (default) | **B — Config-based** |
|---|---|---|
| Reference | [approach-a-content-finder.md](references/approach-a-content-finder.md) | [approach-b-config-based.md](references/approach-b-config-based.md) |
| Source | Custom improvement on the docs' "Advanced" sample | Verified Document Type + template in `assets/`, following the official [tutorial](https://docs.umbraco.com/umbraco-cms/develop-with-umbraco/tutorials/custom-error-page)'s "Recommended" method |
| Custom code | One `IContentLastChanceFinder` + composer (local asset) | None — Umbraco's built-in `ContentFinderByConfigured404` does the work |
| Multi-site (per domain) | Yes — resolves root via `request.Domain` | No — per-culture only |
| Per-environment config | None — resolves by Document Type alias | 404 page GUID in config per environment |

Default to **A**. Offer **B** when the team wants zero custom C# and doesn't need per-domain
multi-site resolution — it's the docs' officially recommended method, so don't hide it. B's Document
Type and template ship as `assets/error-pages-package.xml` + `assets/errorPage404.cshtml`, so it can be
installed as a package or built by hand from that spec.

Both need a published content node either way — prefer the
[Umbraco Developer MCP](https://docs.umbraco.com/umbraco-in-ai/mcp/cms-developer-mcp) for those steps if
available, else guide the user through the backoffice manually.

**Never implement both.** A's `SetContentLastChanceFinder` is
`AddUnique<IContentLastChanceFinder, T>()`, and what it replaces is Umbraco's own
`ContentFinderByConfigured404` — which *is* B's implementation. Registering A silently disables B.

Ask the user before choosing: multi-site by domain? comfortable with a small C# file in the
project? Then read the matching reference and follow it. For 500s, always use
[500-error-controller.md](references/500-error-controller.md).

## Boot Failed errors

If the user also wants to handle failed startups (blank screen / `500.30` / `502.5`), there's
one documented method, no code or backoffice needed: add a static
`wwwroot/config/errors/BootFailed.html` with custom markup, and ensure
`Umbraco:CMS:Hosting:Debug` is `false` in `appsettings.json` (the page only shows with
debugging off). Note: if the app crashes before ASP.NET Core's pipeline initializes, only the
web server (IIS/NGINX/Apache) can serve a fallback page — suggest configuring one there for
full coverage. Offer this proactively when setting up 500 pages; don't wait to be asked.

## Version compatibility

Targets **Umbraco 16.1+** (16.0 has a 404-handling regression, fixed in 16.1 — see the
tutorial's warning).

## Documentation references

- [Implement Custom Error Pages](https://docs.umbraco.com/umbraco-cms/develop-with-umbraco/tutorials/custom-error-page) — source of truth for Approach B's steps/snippets and the underlying reference for A and the 500 controller
- [Custom Routing (IContentLastChanceFinder)](https://docs.umbraco.com/umbraco-cms/extend-your-project/server-side-extensions/custom-routing)
````

- Previous: [plan-zoom-integration](https://syn4pse.dev/terminal/plan-zoom-integration.md)
- Next: [umbraco-sitemap](https://syn4pse.dev/terminal/umbraco-sitemap.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
