umbraco-custom-error-pages

# 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)