Skip to content

Commit 9232e04

Browse files
eshanrnheshanrnh
authored
Merge pull request #7249 from umbraco/custom-error-pages
Updated implementing custom error pages article
2 parents 30313fc + 0489a48 commit 9232e04

File tree

3 files changed

+329
-178
lines changed

3 files changed

+329
-178
lines changed

‎14/umbraco-cms/tutorials/custom-error-page.md‎

Lines changed: 153 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: >-
3-
A set of tutorials creating and implementating custom error pages in an
3+
A set of tutorials for creating and implementating custom error pages in an
44
Umbraco CMS project.
55
---
66

@@ -16,47 +16,59 @@ In Umbraco, in-code error page handling refers to managing and displaying custom
1616

1717
This article contains guides on how to create custom error pages for the most common scenarios:
1818

19-
* [404 errors ("Page not found")](custom-error-page.md#id-404-errors)
20-
* [500 errors ("Internal Server Error")](custom-error-page.md#id-500-errors)
21-
* [Boot Failed errors](custom-error-page.md#errors-with-booting-a-project)
19+
* [404 Errors ("Page not found")](#id-404-errors)
20+
* [500 Errors ("Internal Server Error")](#id-500-errors)
21+
* [Boot Failed Errors](#boot-failed-errors)
2222

2323
{% hint style="info" %}
2424
**Are you looking for a guide to create a custom maintenance page?**
2525

2626
This has been moved to a separate article: [Create a custom maintenance page](create-a-custom-maintenance-page.md).
2727
{% endhint %}
2828

29-
## 404 errors
29+
## 404 Errors
3030

31-
This kind of error can occur when something has been removed, when a path has been changed, or when the chosen path is invalid.
32-
33-
This method will use a 404 page created via the backoffice.
31+
A 404 error occurs when a requested page cannot be found, usually due to deleted content, a changed URL, or an invalid path. In Umbraco, you can create and configure custom 404 pages using content from the backoffice.
3432

3533
### Create a 404 page in the backoffice
3634

37-
1. Navigate to the **Settings** section.
38-
2. Create a new "_Document Type with Template_".
39-
3. Name the Document Type **404**.
40-
4. Adjust the alias to "Page404" before saving the Document Type. Umbraco will not allow you to create a Document Type with a numeric alias.
41-
5. \[Optional] Add properties on the Document Type.
42-
1. In most cases, the 404 not found page would be static.
43-
6. Fill out the Template with your custom markup.
44-
7. Create another **Document Type**, but create it without the Template.
45-
8. Call this Document Type **Statuscodes**.
46-
9. Open the **Structure** Workspace view.
47-
10. Check the **Allow at root** option.
48-
11. Add the **404 Page** Document Type as an **Allowed child note type**.
49-
12. Navigate to the **Content** section.
50-
13. Create a **Statuscodes** content item called **Statuscodes**.
51-
14. Create a **404 Page** content item under the **Statuscodes** content.
52-
53-
### Set a custom 404 page in the configuration
54-
55-
Once that is done, the next step focuses on setting up the appropriate configuration.
56-
57-
1. Take note of the published error page's GUID.
58-
2. Open the `appsettings.json` file in a code editor.
59-
3. Add the `Error404Collection` section to `Umbraco:CMS:Content`, like shown below:
35+
1. Go to the **Settings** section in the Umbraco backoffice.
36+
2. Create a new **Document Type with Template**.
37+
3. Name the Document Type *ErrorPage404*.
38+
4. [Optional] Add any custom properties you want — though most 404 pages are static.
39+
5. Click **Save**.
40+
6. Go to the **Templates** folder.
41+
7. Add your custom markup and design for the error page in the template. In this case, *ErrorPage404*.
42+
8. Click **Save**.
43+
44+
### Create a Container for Status Code Pages
45+
46+
1. Create a new **Document Type**.
47+
2. Name it **Statuscodes**.
48+
3. Go to the **Structure** Workspace view.
49+
* Enable **Allow at root**.
50+
* Add the *ErrorPage404* Document Type as an **Allowed child node types**.
51+
* Click **Choose**.
52+
4. Click **Save**.
53+
54+
### Add the Content
55+
56+
1. Go to the **Content** section.
57+
2. Create a new content node based on the **Statuscodes** Document Type and name it **Statuscodes**.
58+
3. Click **Save** or **Save and Publish**.
59+
4. Under it, create a child node using the *ErrorPage404* Document Type.
60+
5. Name it *Page 404 Not Found* or similar.
61+
* This will be the content shown when a 404 error occurs.
62+
6. Click **Save** or **Save and Publish**.
63+
64+
### Configure the Error Page in `appsettings.json` file
65+
66+
After publishing the 404 page, you’ll need to connect it in your configuration.
67+
68+
1. Go to the **Info** tab of your *Page 404 Not Found* content item in the Backoffice.
69+
2. Copy the **Id** of the page (for example: 9c2b5196-30cd-4416-ae30-94ac2afb1011).
70+
3. Go to your project's `appsettings.json` file.
71+
4. Add the `Error404Collection` setting to `Umbraco:CMS:Content`, like shown below:
6072

6173
```json
6274
{
@@ -66,8 +78,7 @@ Once that is done, the next step focuses on setting up the appropriate configura
6678
"Error404Collection": [
6779
{
6880
"Culture": "default",
69-
// Replace the value for ContentKey with the GUID from step 1
70-
"ContentKey": "81dbb860-a2e3-49df-9a1c-2e04a8012c03"
81+
"ContentKey": "9c2b5196-30cd-4416-ae30-94ac2afb1011"
7182
}
7283
]
7384
}
@@ -76,17 +87,34 @@ Once that is done, the next step focuses on setting up the appropriate configura
7687
}
7788
```
7889

79-
{% hint style="info" %}
80-
With this approach, you can set different 404 pages for specific languages (cultures) - such as `en-us`, `it` etc.
81-
{% endhint %}
90+
Replace the value for `ContentKey` with the ID of your own 404 page.
91+
92+
#### Support for Multilingual Sites
93+
94+
You can define different 404 pages for each language or culture (such as `en-us`, `da-dk`, and so on):
95+
96+
```json
97+
"Error404Collection": [
98+
{
99+
"Culture": "en-us",
100+
"ContentKey": "guid-for-english-404"
101+
},
102+
{
103+
"Culture": "da-dk",
104+
"ContentKey": "guid-for-danish-404"
105+
}
106+
]
107+
```
108+
109+
Each entry maps a culture to its specific 404 page using the content’s GUID.
82110

83111
### Set a custom 404 page using IContentLastChanceFinder
84112

85-
It is also possible to set up a 404 error page programmatically using `IContentLastChanceFinder`. To learn more about `IContentLastChanceFinder` read the [Custom Routing ](../implementation/custom-routing/)article.
113+
It is also possible to set up a 404 error page programmatically using `IContentLastChanceFinder`. To learn more about `IContentLastChanceFinder`, read the [Custom Routing](../implementation/custom-routing/) article.
86114

87-
Before following this example, follow the [Create a 404 page in the backoffice](custom-error-page.md#create-a-404-page-in-the-backoffice) part. The example below will use the `Page404` alias of the Document Type to find and display the error page.
115+
Before following this example, follow the [Create a 404 page in the backoffice](custom-error-page.md#create-a-404-page-in-the-backoffice) part. The example below will use the *errorPage404* alias of the Document Type to find and display the error page.
88116

89-
1. Create a new `.cs` file called `Error404Page` at the root of the project.
117+
1. Create a new `.cs` file called *Error404Page* at the root of the project.
90118
2. Add the following code to the newly created class:
91119

92120
{% code title="Error404Page.cs" lineNumbers="true" %}
@@ -117,7 +145,7 @@ public class Error404Page : IContentLastChanceFinder
117145

118146
// Find the first notFound page at the root level through the published content cache by its documentTypeAlias
119147
// You can make this search as complex as you want, you can return different pages based on anything in the original request
120-
var notFoundPage = umbracoContext.Content?.GetAtRoot().FirstOrDefault(c => c.ContentType.Alias == "Page404");
148+
var notFoundPage = umbracoContext.Content?.GetAtRoot().FirstOrDefault(c => c.ContentType.Alias == "errorPage404");
121149
if (notFoundPage == null)
122150
{
123151
return Task.FromResult(false);
@@ -142,35 +170,53 @@ public class Mycomposer : IComposer
142170
```
143171
{% endcode %}
144172

145-
## 500 errors
173+
## 500 Errors
174+
175+
This section guides you in setting up a custom page for handling internal server errors (500 errors) in your Umbraco site. This setup works when:
176+
177+
* A template throws an error.
178+
* A controller throws an unhandled exception.
179+
* A request hits the application, but something fails during rendering or processing.
146180

147-
The following steps will guide you through setting up a page for internal server errors.
181+
### Create a 500 error page in the Backoffice
148182

149-
### Create a 500-page in the backoffice
183+
1. Go to the **Settings** section in the Umbraco backoffice.
184+
2. Create a new **Document Type with Template** called *ErrorPage500*.
185+
3. [Optional] Add any relevant properties to the Document Type.
186+
4. Click **Save**.
187+
5. Go to the **Templates** folder.
188+
6. Add your custom markup and design for the error page in the template. In this case, *ErrorPage500*.
189+
7. Click **Save**.
150190

151-
The first step is to create the content and structure for it in the Umbraco backoffice.
191+
### Create a Container for Status Code Pages
152192

153-
1. Access the Umbraco Backoffice.
154-
2. Navigate to the **Settings** section.
155-
3. Create a new **Document Type with Template** called **500**.
156-
4. \[Optional] Add relevant properties to the Document Types and define the Template.
157-
5. Fill out the Template with your custom markup.
158-
6. Follow steps 6-9 in the [Create a 404 page in the backoffice](custom-error-page.md#create-a-404-page-in-the-backoffice).
159-
1. This step can be skipped if you already have a content structure for error content nodes in the project.
160-
7. Add the **500** Document Type as an **Allowed child node type** on the **Statuscode** Document Type.
161-
8. Navigate to the **Content** section.
162-
9. Create a **Statuscodes** content item if one does not exist already.
163-
10. Create a **500** content item under the **Statuscodes** content.
193+
1. Create a new **Document Type**.
194+
2. Name it **Statuscodes**.
195+
3. Go to the **Structure** Workspace view.
196+
* Enable **Allow at root**.
197+
* Add the *ErrorPage500* Document Type as an **Allowed child node types**.
198+
* Click **Choose**.
199+
4. Click **Save**.
164200

165-
### Configure the 500 error page programmatically
201+
### Add the Content
166202

167-
The next step in this guide is to configure the 500 pages to be shown when an internal server error occurs.
203+
1. Go to the **Content** section.
204+
2. Create a new content node based on the **Statuscodes** Document Type and name it **Statuscodes**.
205+
3. Click **Save** or **Save and Publish**.
206+
4. Under it, create a child node using the *ErrorPage500* Document Type.
207+
5. Name it *Page 500* or similar.
208+
* This will be the content shown when a 500 error occurs.
168209

169-
1. Create a folder in the root of your Umbraco project, called `Controllers`.
170-
2. Create a file in this folder, called `ErrorController.cs`.
210+
### Configure the 500 Error Page Programmatically
211+
212+
To ensure that the 500 page is shown during server errors, you’ll need to configure a custom error controller and route handling.
213+
214+
1. Create a folder called `Controllers` in the root of your Umbraco project.
215+
2. Add a new file called `ErrorController.cs` in the `Controllers` folder.
171216
3. Add the following code to the file:
172217

173218
{% code title="ErrorController.cs" %}
219+
174220
```csharp
175221
using Microsoft.AspNetCore.Mvc;
176222

@@ -193,29 +239,35 @@ public class ErrorController : Controller
193239
}
194240
}
195241
```
242+
196243
{% endcode %}
197244

198245
{% hint style="info" %}
199-
**Namespace:** Replace _YourProjectNamespace_ with the actual project name. In Visual Studio, you can use _Sync Namespaces_ from the project context menu (in _Solution Explorer_ View).
246+
Replace _YourProjectNamespace_ with the actual project namespace. In Visual Studio, you can right-click the project and select **Sync Namespaces**.
200247
{% endhint %}
201248

202-
4. Add an entry in `appSettings.json` for the new "Error" route:
249+
4. Add the `/error/` route to the list of reserved paths in the `appSettings.json` file:
203250

204251
{% code title="appSettings.json" %}
252+
205253
```json
206254
"Umbraco": {
207255
"CMS": {
208256
"Global": {
209257
"ReservedPaths": "~/app_plugins/,~/install/,~/mini-profiler-resources/,~/umbraco/,~/error/",
210258
...
259+
}
260+
}
261+
}
211262
```
263+
212264
{% endcode %}
213265

214-
5. Update `Program.cs` with the following code:
266+
5. Update `Program.cs` to ensure the error route is triggered by unhandled exceptions:
215267

216268
{% code title="Program.cs" %}
269+
217270
```csharp
218-
...
219271
WebApplication app = builder.Build();
220272

221273
if (builder.Environment.IsDevelopment())
@@ -227,30 +279,61 @@ else
227279
app.UseExceptionHandler("/error");
228280
}
229281
```
282+
230283
{% endcode %}
231284

232285
{% hint style="info" %}
233-
To **test this locally**, in Visual Studio replace `app.UseDeveloperExceptionPage();` by `app.UseExceptionHandler("/error");`. Otherwise, you will get the default error page.
286+
To test locally, replace `app.UseDeveloperExceptionPage();` with `app.UseExceptionHandler("/error");`. Otherwise, you'll get the default .NET error page during development.
234287
{% endhint %}
235288

236-
### How to trigger a 500 error for testing
289+
### Testing Your 500 Error Page
290+
291+
To trigger a 500 error on your site, try introducing a rendering error:
292+
293+
For example, if a Document Type has a property called `test`, it is normally rendered as:
294+
295+
```csharp
296+
@Model.Value("test")
297+
```
298+
299+
To trigger a 500 error, modify it to:
300+
301+
```csharp
302+
@Model.ValueTest("test")
303+
```
304+
305+
This will generate a server-side error, allowing you to verify that your custom 500 page is displayed correctly.
306+
307+
### Handling app startup failures
308+
309+
When Umbraco fails to start, you may see a blank screen or receive a `500.30` or `502.5` error. These indicate the web application crashed or failed to initialize.
310+
311+
#### Why can't the app serve an error page?
312+
313+
During startup, Umbraco relies on the ASP.NET Core pipeline. If the app crashes before this pipeline is fully initialized, it can't handle requests or serve custom error pages. That's why you can't rely on Umbraco or ASP.NET Core routing to show error content at this point as it has already failed. For more information, see the [Handle errors in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling) documentation.
314+
315+
Instead, the web server itself (IIS, NGINX, Apache, and so on) must serve a static fallback 500 page. This page is independent of the application and helps communicate the issue to users when the site is down.
316+
317+
To handle these types of issues:
237318

238-
You can trigger a 500 error on your front end by changing a `Model.Value` property in your template. For example, on a Document Type with a property called `test`. The way to render it in the front would be `Model.Value("test");` To trigger a 500 error page you can add anything after Value such as `Model.ValueTest("test");`
319+
* Configure your web server (IIS, NGINX, Apache) to serve a static HTML 500 page when the app fails to respond.
320+
* Use uptime monitoring to catch failed starts.
321+
* Check Umbraco logs in `App_Data/Logs` for startup errors.
239322

240-
## Errors with booting a project
323+
## Boot Failed Errors
241324

242325
Sometimes you might experience issues with booting up your Umbraco project. This could be a brand new project, or it could be an existing project after an upgrade.
243326

244327
You will be presented with a generic error page when there is an error during boot.
245328

246-
![Boot Failed. Umbraco failed to boot, if you are the owner of the website please see the log file for more details.](../../../10/umbraco-cms/tutorials/images/BootFailedGeneric.png)
329+
![Boot Failed](../../../10/umbraco-cms/tutorials/images/BootFailedGeneric.png)
247330

248-
This page can be overwritten with a custom BootFailed HTML page. Follow the steps below to set it up:
331+
You can replace the default BootFailed page with a custom static `BootFailed.html`. Follow the steps below to set it up:
249332

250333
1. Open your project files.
251334
2. Navigate to `wwwroot/config/errors`
252335
1. If this folder does not exist already, create it.
253-
3. Add a new file called **`BootFailed.html`**.
336+
3. Add a new file called *BootFailed.html*.
254337
4. Add your custom markup to the file.
255338

256339
The `BootFailed.html` page will only be shown if debugging is disabled in the `appsettings.json` file. Debugging is handled using the **Debug** key under `Umbraco:CMS:Hosting`:

0 commit comments

Comments
 (0)