Skip to content

Commit e7ab009

Browse files
eshanrnheshanrnh
committed
Updated article
1 parent 30313fc commit e7ab009

File tree

3 files changed

+322
-168
lines changed

3 files changed

+322
-168
lines changed

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

Lines changed: 152 additions & 68 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,60 @@ 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")](#404-errors)
20+
* [500 Errors ("Internal Server Error")](#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.
31+
A 404 error occurs when a requested page cannot be found—typically because the content has been deleted, the URL path has changed, or the visitor typed an invalid path. In Umbraco, you can create and configure custom 404 pages using content from the backoffice.
3232

33-
This method will use a 404 page created via the backoffice.
33+
This section shows how to set up a custom 404 page:
3434

3535
### Create a 404 page in the backoffice
3636

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:
37+
1. Go to the **Settings** section in the Umbraco backoffice.
38+
2. Create a new **Document Type with Template**.
39+
3. Name the Document Type **ErrorPage404**.
40+
4. [Optional] Add any custom properties you want — though most 404 pages are static.
41+
5. Click **Save**.
42+
6. Go to the **Templates** folder.
43+
7. Add your custom markup and design for the error page in the template. In this case, *ErrorPage404*.
44+
8. Click **Save**.
45+
46+
### Create a Container for Status Code Pages
47+
48+
1. Create a new **Document Type**.
49+
2. Name it **Statuscodes**.
50+
3. Go to the **Structure** Workspace view.
51+
* Enable **Allow at root**.
52+
* Add the **ErrorPage404** Document Type as an **Allowed child node types**.
53+
* Click **Choose**.
54+
4. Click **Save**.
55+
56+
### Add the Content
57+
58+
1. Go to the **Content** section.
59+
2. Create a new content node based on the **Statuscodes** Document Type and name it **Statuscodes**.
60+
3. Click **Save** or **Save and Publish**.
61+
4. Under it, create a child node using the **ErrorPage404** Document Type.
62+
5. Name it *Page 404 Not Found* or similar.
63+
* This will be the content shown when a 404 error occurs.
64+
65+
### Configure the Error Page in `appsettings.json` file
66+
67+
After publishing the 404 page, you’ll need to connect it in your configuration.
68+
69+
1. Go to the **Info** tab of your *Page 404 Not Found* content item in the Backoffice.
70+
2. Copy the **Id** of the page (for example: 9c2b5196-30cd-4416-ae30-94ac2afb1011).
71+
3. Go to your project's `appsettings.json` file.
72+
4. Add the `Error404Collection` setting to `Umbraco:CMS:Content`, like shown below:
6073

6174
```json
6275
{
@@ -66,8 +79,7 @@ Once that is done, the next step focuses on setting up the appropriate configura
6679
"Error404Collection": [
6780
{
6881
"Culture": "default",
69-
// Replace the value for ContentKey with the GUID from step 1
70-
"ContentKey": "81dbb860-a2e3-49df-9a1c-2e04a8012c03"
82+
"ContentKey": "9c2b5196-30cd-4416-ae30-94ac2afb1011"
7183
}
7284
]
7385
}
@@ -76,15 +88,32 @@ Once that is done, the next step focuses on setting up the appropriate configura
7688
}
7789
```
7890

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 %}
91+
Replace the value for `ContentKey` with the ID of your own 404 page.
92+
93+
#### Support for Multilingual Sites
94+
95+
You can define different 404 pages for each language or culture (such as `en-us`, `da-dk`, and so on):
96+
97+
```json
98+
"Error404Collection": [
99+
{
100+
"Culture": "en-us",
101+
"ContentKey": "guid-for-english-404"
102+
},
103+
{
104+
"Culture": "da-dk",
105+
"ContentKey": "guid-for-danish-404"
106+
}
107+
]
108+
```
109+
110+
Each entry maps a culture to its specific 404 page using the content’s GUID.
82111

83112
### Set a custom 404 page using IContentLastChanceFinder
84113

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.
114+
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.
86115

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.
116+
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.
88117

89118
1. Create a new `.cs` file called `Error404Page` at the root of the project.
90119
2. Add the following code to the newly created class:
@@ -117,7 +146,7 @@ public class Error404Page : IContentLastChanceFinder
117146

118147
// Find the first notFound page at the root level through the published content cache by its documentTypeAlias
119148
// 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");
149+
var notFoundPage = umbracoContext.Content?.GetAtRoot().FirstOrDefault(c => c.ContentType.Alias == "errorPage404");
121150
if (notFoundPage == null)
122151
{
123152
return Task.FromResult(false);
@@ -142,35 +171,53 @@ public class Mycomposer : IComposer
142171
```
143172
{% endcode %}
144173

145-
## 500 errors
174+
## 500 Errors
146175

147-
The following steps will guide you through setting up a page for internal server errors.
176+
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:
148177

149-
### Create a 500-page in the backoffice
178+
* A template throws an error.
179+
* A controller throws an unhandled exception.
180+
* A request hits the application, but something fails during rendering or processing.
150181

151-
The first step is to create the content and structure for it in the Umbraco backoffice.
182+
### Create a 500 error page in the Backoffice
152183

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

165-
### Configure the 500 error page programmatically
192+
### Create a Container for Status Code Pages
166193

167-
The next step in this guide is to configure the 500 pages to be shown when an internal server error occurs.
194+
1. Create a new **Document Type**.
195+
2. Name it **Statuscodes**.
196+
3. Go to the **Structure** Workspace view.
197+
* Enable **Allow at root**.
198+
* Add the **ErrorPage500** Document Type as an **Allowed child node types**.
199+
* Click **Choose**.
200+
4. Click **Save**.
168201

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`.
202+
### Add the Content
203+
204+
1. Go to the **Content** section.
205+
2. Create a new content node based on the **Statuscodes** Document Type and name it **Statuscodes**.
206+
3. Click **Save** or **Save and Publish**.
207+
4. Under it, create a child node using the **ErrorPage500** Document Type.
208+
5. Name it *Page 500* or similar.
209+
* This will be the content shown when a 500 error occurs.
210+
211+
### Configure the 500 Error Page Programmatically
212+
213+
To ensure that the 500 page is shown during server errors, you’ll need to configure a custom error controller and route handling.
214+
215+
1. Create a folder called `Controllers` in the root of your Umbraco project.
216+
2. Add a new file called `ErrorController.cs` in the `Controllers` folder.
171217
3. Add the following code to the file:
172218

173219
{% code title="ErrorController.cs" %}
220+
174221
```csharp
175222
using Microsoft.AspNetCore.Mvc;
176223

@@ -193,29 +240,35 @@ public class ErrorController : Controller
193240
}
194241
}
195242
```
243+
196244
{% endcode %}
197245

198246
{% 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).
247+
Replace _YourProjectNamespace_ with the actual project namespace. In Visual Studio, you can right-click the project and select **Sync Namespaces**.
200248
{% endhint %}
201249

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

204252
{% code title="appSettings.json" %}
253+
205254
```json
206255
"Umbraco": {
207256
"CMS": {
208257
"Global": {
209258
"ReservedPaths": "~/app_plugins/,~/install/,~/mini-profiler-resources/,~/umbraco/,~/error/",
210259
...
260+
}
261+
}
262+
}
211263
```
264+
212265
{% endcode %}
213266

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

216269
{% code title="Program.cs" %}
270+
217271
```csharp
218-
...
219272
WebApplication app = builder.Build();
220273

221274
if (builder.Environment.IsDevelopment())
@@ -227,30 +280,61 @@ else
227280
app.UseExceptionHandler("/error");
228281
}
229282
```
283+
230284
{% endcode %}
231285

232286
{% 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.
287+
To test locally, replace `app.UseDeveloperExceptionPage();` with `app.UseExceptionHandler("/error");`. Otherwise, you'll get the default .NET error page during development.
234288
{% endhint %}
235289

236-
### How to trigger a 500 error for testing
290+
### Testing Your 500 Error Page
291+
292+
To trigger a 500 error on your site, try introducing a rendering error:
293+
294+
For example, if a Document Type has a property called `test`, it is normally rendered as:
295+
296+
```csharp
297+
@Model.Value("test")
298+
```
299+
300+
To trigger a 500 error, modify it to:
301+
302+
```csharp
303+
@Model.ValueTest("test")
304+
```
305+
306+
This will generate a server-side error, allowing you to verify that your custom 500 page is displayed correctly.
307+
308+
### Handling app startup failures
309+
310+
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.
311+
312+
#### Why can't the app serve an error page?
313+
314+
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.
315+
316+
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.
317+
318+
To handle these types of issues:
237319

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");`
320+
* Configure your web server (IIS, NGINX, Apache) to serve a static HTML 500 page when the app fails to respond.
321+
* Use uptime monitoring to catch failed starts.
322+
* Check Umbraco logs in `App_Data/Logs` for startup errors.
239323

240-
## Errors with booting a project
324+
## Boot Failed Errors
241325

242326
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.
243327

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

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)
330+
![Boot Failed](../../../10/umbraco-cms/tutorials/images/BootFailedGeneric.png)
247331

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

250334
1. Open your project files.
251335
2. Navigate to `wwwroot/config/errors`
252336
1. If this folder does not exist already, create it.
253-
3. Add a new file called **`BootFailed.html`**.
337+
3. Add a new file called *BootFailed.html*.
254338
4. Add your custom markup to the file.
255339

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