Merge pull request #7106 from umbraco/500-errors

Feedback on 500 error page

Author: eshanrnh

.github/styles/UmbracoDocs/Acronyms.yml

@@ -90,3 +90,4 @@ exceptions:
     - SSD
     - ASCII
     - CMD
+    - NGINX

15/umbraco-cms/tutorials/custom-error-page.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  A set of tutorials creating and implementating custom error pages in an
+  A set of tutorials for creating and implementating custom error pages in an
   Umbraco CMS project.
 ---
 
@@ -16,17 +16,17 @@ In Umbraco, in-code error page handling refers to managing and displaying custom
 
 This article contains guides on how to create custom error pages for the most common scenarios:
 
-* [404 errors ("Page not found")](custom-error-page.md#id-404-errors)
-* [500 errors ("Internal Server Error")](custom-error-page.md#id-500-errors)
-* [Boot Failed errors](custom-error-page.md#errors-with-booting-a-project)
+* [404 Errors ("Page not found")](#404-errors)
+* [500 Errors ("Internal Server Error")](#500-errors)
+* [Boot Failed Errors](#boot-failed-errors)
 
 {% hint style="info" %}
 **Are you looking for a guide to create a custom maintenance page?**
 
 This has been moved to a separate article: [Create a custom maintenance page](create-a-custom-maintenance-page.md).
 {% endhint %}
 
-## 404 errors
+## 404 Errors
 
 This kind of error can occur when something has been removed, when a path has been changed, or when the chosen path is invalid.
 
@@ -37,7 +37,7 @@ This method will use a 404 page created via the backoffice.
 1. Navigate to the **Settings** section.
 2. Create a new "_Document Type with Template_".
 3. Name the Document Type **404**.
-4. \[Optional] Add properties on the Document Type.
+4. [Optional] Add properties on the Document Type.
    1. In most cases, the 404 not found page would be static.
 5. Fill out the Template with your custom markup.
 6. Create another **Document Type**, but create it without the Template.
@@ -65,7 +65,6 @@ Once that is done, the next step focuses on setting up the appropriate configura
                 "Error404Collection": [
                     {
                         "Culture": "default",
-                        // Replace the value for ContentKey with the GUID from step 1
                         "ContentKey": "81dbb860-a2e3-49df-9a1c-2e04a8012c03"
                     }
                 ]
@@ -75,9 +74,22 @@ Once that is done, the next step focuses on setting up the appropriate configura
 }
 ```
 
-{% hint style="info" %}
-With this approach, you can set different 404 pages for specific languages (cultures) - such as `en-us`, `it` etc.
-{% endhint %}
+In the above code sample, replace the value for `ContentKey` with the GUID from step 1.
+
+With this approach, you can set different 404 pages for specific languages/cultures (such as `en-us`, `da-dk`, and so on):
+
+```json
+"Error404Collection": [
+  {
+    "Culture": "en-us",
+    "ContentKey": "guid-for-english-404"
+  },
+  {
+    "Culture": "da-dk",
+    "ContentKey": "guid-for-danish-404"
+  }
+]
+```
 
 ### Set a custom 404 page using IContentLastChanceFinder
 
@@ -141,35 +153,38 @@ public class Mycomposer : IComposer
 ```
 {% endcode %}
 
-## 500 errors
+## 500 Errors
 
-The following steps will guide you through setting up a page for internal server errors.
+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:
 
-### Create a 500-page in the backoffice
+* A template throws an error.
+* A controller throws an unhandled exception.
+* A request hits the application, but something fails during rendering or processing.
 
-The first step is to create the content and structure for it in the Umbraco backoffice.
+### Create a 500 error page in the Backoffice
 
 1. Access the Umbraco Backoffice.
 2. Navigate to the **Settings** section.
-3. Create a new **Document Type with Template** called **500**.
-4. \[Optional] Add relevant properties to the Document Types and define the Template.
+3. Create a new **Document Type with Template** called *500*.
+4. [Optional] Add relevant properties to the Document Types and define the template layout.
 5. Fill out the Template with your custom markup.
-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).
-   1. This step can be skipped if you already have a content structure for error content nodes in the project.
+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) section.
+   * You can skip this if you already have a structure for status code content nodes.
 7. Add the **500** Document Type as an **Allowed child node type** on the **Statuscode** Document Type.
-8. Navigate to the **Content** section.
+8. Go to the **Content** section.
 9. Create a **Statuscodes** content item if one does not exist already.
-10. Create a **500** content item under the **Statuscodes** content.
+10. Create a new content node of type **500** under the **Statuscodes** content node.
 
-### Configure the 500 error page programmatically
+### Configure programmatic error handling
 
-The next step in this guide is to configure the 500 pages to be shown when an internal server error occurs.
+Now configure the application to display the 500 error page when internal server errors occur.
 
-1. Create a folder in the root of your Umbraco project, called `Controllers`.
-2. Create a file in this folder, called `ErrorController.cs`.
+1. Create a folder called `Controllers` in the root of your Umbraco project.
+2. Create a new file called `ErrorController.cs` in the `Controllers` folder.
 3. Add the following code to the file:
 
 {% code title="ErrorController.cs" %}
+
 ```csharp
 using Microsoft.AspNetCore.Mvc;
 
@@ -192,29 +207,35 @@ public class ErrorController : Controller
     }
 }
 ```
+
 {% endcode %}
 
 {% hint style="info" %}
-**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).
+Replace _YourProjectNamespace_ with the actual project name. In Visual Studio, you can use _Sync Namespaces_ from the project context menu (in _Solution Explorer_ View).
 {% endhint %}
 
-4. Add an entry in `appSettings.json` for the new "Error" route:
+4. Add the `/error/` route to the list of reserved paths in the `appSettings.json` file:
 
 {% code title="appSettings.json" %}
+
 ```json
 "Umbraco": {
 "CMS": {
     "Global": {
     "ReservedPaths": "~/app_plugins/,~/install/,~/mini-profiler-resources/,~/umbraco/,~/error/",
     ...
+    }
+  }
+}
 ```
+
 {% endcode %}
 
-5. Update `Program.cs` with the following code:
+5. Update `Program.cs` to ensure the error route is triggered by unhandled exceptions:
 
 {% code title="Program.cs" %}
+
 ```csharp
-...
 WebApplication app = builder.Build();
 
 if (builder.Environment.IsDevelopment())
@@ -226,30 +247,59 @@ else
     app.UseExceptionHandler("/error");
 }
 ```
+
 {% endcode %}
 
 {% hint style="info" %}
-To **test this locally**, in Visual Studio replace `app.UseDeveloperExceptionPage();` by `app.UseExceptionHandler("/error");`. Otherwise, you will get the default error page.
+To test this locally, replace `app.UseDeveloperExceptionPage();` by `app.UseExceptionHandler("/error");`. Otherwise, you will get the default error page.
 {% endhint %}
 
-### How to trigger a 500 error for testing
+### Trigger a 500 error (for testing)
+
+To trigger a 500 error, change a `Model.Value` property in your template. For example, if your Document Type has a property called `test`you would normally render it with:
+
+```csharp
+@Model.Value("test")
+```
+
+To deliberately cause an error, change it to something invalid like:
+
+```csharp
+@Model.ValueTest("test")
+```
+
+This should throw an error, triggering your custom 500 page.
+
+### Handling app startup failures
+
+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.
+
+#### Why can't the app serve an error page?
+
+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.
+
+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.
+
+To handle these types of issues:
 
-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");`
+* Configure your web server (IIS, NGINX, Apache) to serve a static HTML 500 page when the app fails to respond.
+* Use uptime monitoring to catch failed starts.
+* Check Umbraco logs in `App_Data/Logs` for startup errors.
 
-## Errors with booting a project
+## Boot Failed Errors
 
 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.
 
 You will be presented with a generic error page when there is an error during boot.
 
-![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)
+![Boot Failed](../../../10/umbraco-cms/tutorials/images/BootFailedGeneric.png)
 
-This page can be overwritten with a custom BootFailed HTML page. Follow the steps below to set it up:
+You can replace the default BootFailed page with a custom static `BootFailed.html`. Follow the steps below to set it up:
 
 1. Open your project files.
 2. Navigate to `wwwroot/config/errors`
    1. If this folder does not exist already, create it.
-3. Add a new file called **`BootFailed.html`**.
+3. Add a new file called *BootFailed.html*.
 4. Add your custom markup to the file.
 
 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`: