Published: October 02 2020

ASP.NET Core 3.1 - Global Error Handler Tutorial

Built with ASP.NET Core 3.1

Other versions available:

This is a quick post to show how to implement a global exception handler in ASP.NET Core 3.1.

These are the main pieces involved in the error handling process with a brief description of each:

  • Global Error Handler Middleware - custom middleware that catches and handles all exceptions, and determines which HTTP response code to return based on the exception type.
  • Custom App Exception - a custom exception class used to differentiate between handled exceptions that return a 400 response and unhandled exceptions that return a 500 response.
  • Startup.cs - the ASP.NET Core startup class that adds the global error handler middleware to the application request pipeline.
  • Example Error Service - an example service that shows how to throw a custom exception that will be handled by the global error handler.

The below example code snippets are from a boilerplate authentication api tutorial I posted recently, for the full tutorial or to download and test the code see ASP.NET Core 3.1 - Boilerplate API with Email Sign Up, Verification, Authentication & Forgot Password.


Global Error Handler Middleware

The global error handler middleware is used catch all exceptions thrown by the api in a single place, removing the need for duplicated error handling code throughout the application. It's configured as middleware in the Configure method of the Startup.cs class.

Errors of type AppException are treated as custom (app specific) errors that return a 400 Bad Request response, the ASP.NET built-in KeyNotFoundException class is used to return 404 Not Found responses, all other exceptions are unhandled and return a 500 Internal Server Error response.

See the example service for examples of how to throw a custom app exception or not found exception that will be handled by the global error handler.

using Microsoft.AspNetCore.Http;
using System;
using System.Collections.Generic;
using System.Net;
using System.Text.Json;
using System.Threading.Tasks;
using WebApi.Helpers;

namespace WebApi.Middleware
    public class ErrorHandlerMiddleware
        private readonly RequestDelegate _next;

        public ErrorHandlerMiddleware(RequestDelegate next)
            _next = next;

        public async Task Invoke(HttpContext context)
                await _next(context);
            catch (Exception error)
                var response = context.Response;
                response.ContentType = "application/json";

                    case AppException e:
                        // custom application error
                        response.StatusCode = (int)HttpStatusCode.BadRequest;
                    case KeyNotFoundException e:
                        // not found error
                        response.StatusCode = (int)HttpStatusCode.NotFound;
                        // unhandled error
                        response.StatusCode = (int)HttpStatusCode.InternalServerError;

                var result = JsonSerializer.Serialize(new { message = error?.Message });
                await response.WriteAsync(result);

Custom App Exception

The app exception is a custom exception class used to differentiate between handled and unhandled exceptions. Handled exceptions are ones generated by the application and used to display friendly error messages to the client, for example business logic or validation exceptions caused by incorrect input from the user. Unhandled exceptions are generated by the .NET framework and can be caused by bugs in the application code.

using System;
using System.Globalization;

namespace WebApi.Helpers
    // custom exception class for throwing application specific exceptions 
    // that can be caught and handled within the application
    public class AppException : Exception
        public AppException() : base() {}

        public AppException(string message) : base(message) { }

        public AppException(string message, params object[] args) 
            : base(String.Format(CultureInfo.CurrentCulture, message, args))

Startup Class

The startup class configures the services available to the ASP.NET Core Dependency Injection (DI) container in the ConfigureServices method, and configures the ASP.NET Core request pipeline for the application in the Configure method.

The global error handler middleware is configured on line 60 by calling app.UseMiddleware<ErrorHandlerMiddleware>();

using AutoMapper;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using System;
using WebApi.Helpers;
using WebApi.Middleware;
using WebApi.Services;

namespace WebApi
    public class Startup
        public IConfiguration Configuration { get; }

        public Startup(IConfiguration configuration)
            Configuration = configuration;

        // add services to the DI container
        public void ConfigureServices(IServiceCollection services)
            services.AddControllers().AddJsonOptions(x => x.JsonSerializerOptions.IgnoreNullValues = true);

            // configure strongly typed settings object

            // configure DI for application services
            services.AddScoped<IAccountService, AccountService>();
            services.AddScoped<IEmailService, EmailService>();

        // configure the HTTP request pipeline
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env, DataContext context)
            // migrate database changes on startup (includes initial db creation)

            // generated swagger json and swagger ui middleware
            app.UseSwaggerUI(x => x.SwaggerEndpoint("/swagger/v1/swagger.json", "ASP.NET Core Sign-up and Verification API"));


            // global cors policy
            app.UseCors(x => x
                .SetIsOriginAllowed(origin => true)

            // global error handler

            // custom jwt auth middleware

            app.UseEndpoints(x => x.MapControllers());

Example Error Service

This is an example service to show how to throw custom app exceptions and not found exceptions that will be handled by the global error handler middleware.

using System.Collections.Generic;
using WebApi.Helpers;

namespace WebApi.Services
    public class ExampleErrorService
        public void ExampleErrors() {
            // a custom app exception that will return a 400 response
            throw new AppException("Email or password is incorrect");

            // a key not found exception that will return a 404 response
            throw new KeyNotFoundException("Account not found");


Need Some ASP.NET Core Help?

Search fiverr for freelance ASP.NET Core developers.

Follow me for updates

On Twitter or RSS.

When I'm not coding...

Me and Tina are on a motorcycle adventure around Australia.
Come along for the ride!


Supported by