Download source code from GitHub

Problem

How to create error pages for specific HTTP status codes in ASP.NET Core.

Solution

Create an empty project and update Startup to add middleware for Status Code Pages:

public class Startup
    {
        public void ConfigureServices(
            IServiceCollection services)
        {
            services.AddMvc();
        }

        public void Configure(
            IApplicationBuilder app, 
            IHostingEnvironment env)
        {
            app.UseStatusCodePagesWithReExecute("/Errors/Index", "?statusCode={0}");

            app.UseMvcWithDefaultRoute();
        }
    }

Note: The {0} is substituted with the HTTP status code that triggered the execution middleware.

Add Errors controller to catch status code errors:

public class ErrorsController : Controller
    {
        public IActionResult Index(int statusCode)
        {
            var feature = HttpContext.Features.Get<IStatusCodeReExecuteFeature>();

            ViewBag.StatusCode = statusCode;
            ViewBag.OriginalPath = feature?.OriginalPath;
            ViewBag.OriginalQueryString = feature?.OriginalQueryString;

            return View();
        }
    }

Add a view for Index view and display error details:

<p>Status Code: <b>@ViewBag.StatusCode</b></p>
<p>OriginalPath: <b>@ViewBag.OriginalPath</b></p>
<p>OriginalQueryString: <b>@ViewBag.OriginalQueryString</b></p>

Add Home controller to return status codes:

public class HomeController : Controller
    {
        public IActionResult Index() => View();

        public IActionResult Throw404(int id) => StatusCode(404);

        public IActionResult Throw412(int id) => StatusCode(412);

        public IActionResult Throw500(int id) => StatusCode(500);
    }

Add a view for Index view:

<p>You've reached Home</p>

<ul>
    <li><a href="/Home/Throw404?id=1">404 (Not Foud)</a></li>
    <li><a href="/Home/Throw412?id=2">412 (Precondition Failed)</a></li>
    <li><a href="/Home/Throw500?id=3">500 (Internal Server Error)</a></li>
</ul>

Run and click one of the links, you’ll the view from Errors controller, note however that the URL doesn’t change:

The request made shows the status code error too:

Discussion

Exception handling middleware (as discussed here) will catch unhandled exceptions, however if you want to display error pages for individual HTTP status codes, then the framework provides another middleware for this purpose.

When configuring the middleware, you have the option to either re-execute or re-direct the request. The above solution shows re-execute, where the server rewrites the request. The result is that URL reflects the path browsed by the user, rather than the path to errors page.

Another option is to configure re-direct when setting up middleware:

public void Configure(
            IApplicationBuilder app, 
            IHostingEnvironment env)
        {
            app.UseStatusCodePagesWithRedirects("/Errors/Index?statusCode={0}");

            app.UseMvcWithDefaultRoute();
        }

However, now, the browser will display the path to errors page:

And as it’s a redirect, server will first send a 302 (Found) to the browser, which will make a subsequent request to the errors page:

ASP.NET Core 2.0 Status Code Pages