umbraco 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, 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 | approach-b-config-based.md |
| Source | Custom improvement on the docs' "Advanced" sample | Verified Document Type + template in assets/, following the official tutorial'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 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.
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 — source of truth for Approach B's steps/snippets and the underlying reference for A and the 500 controller
- Custom Routing (IContentLastChanceFinder)