Published: May 29 2021

.NET 5.0 - Global Error Handler Tutorial

Built with .NET 5.0

Other versions available:

This is a quick post to show how to implement a global exception handler in .NET 5.0.

These are the main pieces involved in the error handling process that we'll cover in this tutorial:

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

The below code snippets are taken from a .NET API tutorial I posted recently, for the full tutorial or to download and test the code locally see .NET 5.0 - Simple API for Authentication, Registration and User Management.


Global Error Handler Middleware

The global error handler is used catch all errors and remove the need for duplicated error handling code throughout the .NET api. It's configured as middleware in the Configure method of the project startup file.

Errors of type AppException are treated as custom (app specific) errors that return a 400 Bad Request response, the .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 an AppException or KeyNotFoundException that will be handled by this error handler middleware.

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

namespace WebApi.Helpers
    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);

App Exception

The app exception is a custom exception class used to differentiate between handled and unhandled exceptions in the .NET API. Handled exceptions are generated by application code and used to return friendly error messages, for example business logic or validation exceptions caused by invalid request parameters, whereas unhandled exceptions are generated by the .NET framework or caused by bugs in 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 .NET Dependency Injection (DI) container in the ConfigureServices method, and configures the .NET request pipeline for the application in the Configure method.

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

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

namespace WebApi
    public class Startup
        private readonly IWebHostEnvironment _env;
        private readonly IConfiguration _configuration;

        public Startup(IWebHostEnvironment env, IConfiguration configuration)
            _env = env;
            _configuration = configuration;

        // add services to the DI container
        public void ConfigureServices(IServiceCollection services)
            // use sql server db in production and sqlite db in development
            if (_env.IsProduction())
                services.AddDbContext<DataContext, SqliteDataContext>();


            // configure strongly typed settings objects

            // configure DI for application services
            services.AddScoped<IJwtUtils, JwtUtils>();
            services.AddScoped<IUserService, UserService>();

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


            // global cors policy
            app.UseCors(x => x

            // global error handler

            // custom jwt auth middleware

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

Example Error Throwing 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, resulting in 400 and 404 HTTP responses respectively.

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 .NET Help?

Search fiverr for freelance .NET 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