Global Exception Handling in ASP.NET Core - The Complete Guide for .NET 10

Exception handling can make or break your application. If exceptions aren’t handled properly, your API could leak sensitive stack traces, return inconsistent error formats, or worse — crash entirely. I’ve seen production systems go down because a single unhandled null reference propagated through the entire request pipeline.

In this guide, we’ll cover everything you need to know about global exception handling in ASP.NET Core — from the old try-catch approach to the modern IExceptionHandler introduced in .NET 8, all the way to the new .NET 10 features like SuppressDiagnosticsCallback. By the end, you’ll have a production-ready exception handling setup that’s clean, maintainable, and follows best practices.

TL;DR - Which Approach Should You Use?

If you’re in a hurry, here’s the quick comparison:

Bottom line: If you’re on .NET 8 or later, use IExceptionHandler. It’s cleaner, more testable, and gives you the flexibility to handle different exception types exactly how you want.

What Are Exceptions in .NET?

Before diving into handling mechanisms, let’s quickly cover the basics. Exceptions in .NET are objects that inherit from System.Exception and represent errors that occur during program execution. When something goes wrong, you throw an exception, and it propagates up the call stack until something catches it.

Common exceptions you’ll encounter:

• NullReferenceException — The classic “object reference not set” error
• ArgumentNullException — When a required argument is null
• InvalidOperationException — When an operation isn’t valid for the current state
• KeyNotFoundException — When a dictionary lookup fails
• HttpRequestException — When an HTTP call fails

The goal of global exception handling is to catch any unhandled exceptions before they reach the client, log them properly, and return a consistent, safe error response.

The Evolution of Exception Handling in ASP.NET Core

ASP.NET Core has evolved significantly in how it handles exceptions. Let’s walk through each approach so you understand why IExceptionHandler is now the recommended solution.

1. Try-Catch Blocks (The Naive Approach)

This is what most developers start with:

[HttpGet("{id}")]
public IActionResult GetProduct(int id)
{
    try
    {
        var product = _productService.GetById(id);
        return Ok(product);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error fetching product {ProductId}", id);
        return StatusCode(500, "An error occurred");
    }
}

This works, but imagine having to write this in every single endpoint. Your codebase becomes cluttered with repetitive try-catch blocks, and there’s no guarantee that every developer on the team will handle errors consistently.

Verdict: Use try-catch only for specific scenarios where you need localized error recovery — not for global exception handling.

2. Built-in UseExceptionHandler Middleware

ASP.NET Core provides a built-in middleware that catches exceptions from the pipeline:

1
app.UseExceptionHandler(options =>
2
{
3
    options.Run(async context =>
4
    {
5
        context.Response.StatusCode = StatusCodes.Status500InternalServerError;
6
        context.Response.ContentType = "application/json";
7

8
        var exceptionFeature = context.Features.Get<IExceptionHandlerFeature>();
9
        if (exceptionFeature is not null)
10
        {
11
            var error = new { message = "An unexpected error occurred" };
12
            await context.Response.WriteAsJsonAsync(error);
13
        }
14
    });
15
});

Let me break this down:

• Line 1: UseExceptionHandler adds the exception handling middleware to the pipeline. Any unhandled exception from downstream middleware or endpoints will be caught here.
• Line 3: options.Run registers a terminal middleware — it handles the request and doesn’t call the next middleware.
• Lines 5-6: We set the HTTP status code to 500 and content type to JSON. This ensures the client knows what kind of response to expect.
• Line 8: IExceptionHandlerFeature gives us access to the original exception. ASP.NET Core stores exception details in this feature when an error occurs.
• Lines 11-12: We create an anonymous object and serialize it as JSON. Simple, but not ideal for production.

This is better — all exceptions flow through one place. But it’s limited. You’re writing inline code in Program.cs, which isn’t great for testing or complex logic. Plus, handling different exception types becomes messy fast.

3. Custom Middleware (Pre-.NET 8 Approach)

Before .NET 8, the cleanest approach was building custom middleware:

1
public class ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
2
{
3
    public async Task InvokeAsync(HttpContext context)
4
    {
5
        try
6
        {
7
            await next(context);
8
        }
9
        catch (Exception ex)
10
        {
11
            logger.LogError(ex, "Unhandled exception occurred");
12
            await HandleExceptionAsync(context, ex);
13
        }
14
    }
15

16
    private static async Task HandleExceptionAsync(HttpContext context, Exception exception)
17
    {
18
        context.Response.ContentType = "application/json";
19
        context.Response.StatusCode = exception switch
20
        {
21
            KeyNotFoundException => StatusCodes.Status404NotFound,
22
            ArgumentException => StatusCodes.Status400BadRequest,
23
            _ => StatusCodes.Status500InternalServerError
24
        };
25

26
        var problemDetails = new ProblemDetails
27
        {
28
            Status = context.Response.StatusCode,
29
            Title = "An error occurred",
30
            Detail = exception.Message
31
        };
32

33
        await context.Response.WriteAsJsonAsync(problemDetails);
34
    }
35
}

Here’s what’s happening:

• Line 1: We’re using a primary constructor (C# 12 feature) to inject RequestDelegate and ILogger. The RequestDelegate next represents the next middleware in the pipeline.
• Lines 5-7: The try block wraps the call to next(context). This means any exception thrown by downstream middleware or endpoints gets caught here.
• Lines 9-12: When an exception occurs, we log it and pass it to our handling method.
• Lines 19-24: This is where it gets interesting. We use a switch expression to map exception types to HTTP status codes. KeyNotFoundException becomes 404, ArgumentException becomes 400, and everything else defaults to 500.
• Lines 26-31: We build a ProblemDetails object — this is the RFC 7807 standard for error responses. It gives clients a consistent structure to parse.
• Line 33: Finally, we serialize the problem details as JSON and write it to the response.

Register it in Program.cs:

app.UseMiddleware<ExceptionHandlingMiddleware>();

This works well and was the standard for years. But .NET 8 introduced something better.

4. IExceptionHandler (The Modern Way - .NET 8+)

IExceptionHandler is an interface that lets you handle exceptions in a clean, testable, and modular way. It plugs directly into ASP.NET Core’s built-in exception handling middleware — so when Microsoft improves that middleware, you get the benefits for free.

Here’s why it’s superior:

• Dependency injection — Your handlers are registered in DI, so you can inject services
• Testable — Easy to unit test without spinning up the entire HTTP pipeline
• Chainable — Register multiple handlers for different exception types
• Framework-integrated — Uses the same middleware Microsoft maintains

Let’s dive deep into how to use it.

Creating Custom Exception Classes

Before implementing the handler, let’s set up proper custom exceptions. This makes your code more readable and your error handling more precise.

Create a base exception class:

1
public abstract class AppException : Exception
2
{
3
    public HttpStatusCode StatusCode { get; }
4

5
    protected AppException(string message, HttpStatusCode statusCode = HttpStatusCode.InternalServerError)
6
        : base(message)
7
    {
8
        StatusCode = statusCode;
9
    }
10
}

Let me explain why this design matters:

• Line 1: The class is abstract — you can’t instantiate it directly. This forces developers to create specific exception types like NotFoundException instead of throwing generic AppException.
• Line 3: We store the HttpStatusCode as a property. This is the key insight — the exception knows what HTTP status it should return. Your handler doesn’t need complex switch statements to figure this out.
• Lines 5-8: The constructor takes a message and an optional status code (defaulting to 500). We pass the message to the base Exception class and store the status code.

Now create specific exceptions:

1
public sealed class NotFoundException : AppException
2
{
3
    public NotFoundException(string resourceName, object key)
4
        : base($"{resourceName} with identifier '{key}' was not found.", HttpStatusCode.NotFound)
5
    {
6
    }
7
}
8

9
public sealed class BadRequestException : AppException
10
{
11
    public BadRequestException(string message)
12
        : base(message, HttpStatusCode.BadRequest)
13
    {
14
    }
15
}
16

17
public sealed class ConflictException : AppException
18
{
19
    public ConflictException(string message)
20
        : base(message, HttpStatusCode.Conflict)
21
    {
22
    }
23
}
24

25
public sealed class ValidationException : AppException
26
{
27
    public IDictionary<string, string[]> Errors { get; }
28

29
    public ValidationException(IDictionary<string, string[]> errors)
30
        : base("One or more validation errors occurred.", HttpStatusCode.BadRequest)
31
    {
32
        Errors = errors;
33
    }
34

35
    public ValidationException(string field, string error)
36
        : base("One or more validation errors occurred.", HttpStatusCode.BadRequest)
37
    {
38
        Errors = new Dictionary<string, string[]>
39
        {
40
            { field, [error] }
41
        };
42
    }
43
}

Notice a few things:

• Line 1: Each exception is sealed — no further inheritance needed. This is a small optimization and makes the intent clear.
• Lines 3-4: NotFoundException takes resourceName and key parameters. This creates a descriptive message like “Product with identifier ‘123’ was not found.” Anyone reading logs instantly knows what went wrong and for which resource.
• Lines 9-12: BadRequestException is simpler — it just takes a message and maps to 400 Bad Request.
• Lines 17-20: ConflictException maps to 409 Conflict — useful for duplicate entries or concurrent modification errors.
• Lines 23-38: ValidationException is special — it carries field-level errors in a dictionary. This works seamlessly with ValidationProblemDetails for form validation scenarios. The two constructors allow either a full dictionary of errors or a single field/error pair for convenience.

Now you can throw meaningful exceptions from your services:

public Product GetById(Guid id)
{
    var product = _repository.Find(id);
    if (product is null)
    {
        throw new NotFoundException("Product", id);
    }
    return product;
}

Get the point? The exception carries all the context needed for proper error handling downstream.

Implementing IExceptionHandler in .NET 10

Here’s a production-ready implementation that uses IProblemDetailsService for RFC 9457-compliant responses:

1
using Microsoft.AspNetCore.Diagnostics;
2
using Microsoft.AspNetCore.Mvc;
3

4
public sealed class GlobalExceptionHandler(
5
    ILogger<GlobalExceptionHandler> logger,
6
    IProblemDetailsService problemDetailsService) : IExceptionHandler
7
{
8
    public async ValueTask<bool> TryHandleAsync(
9
        HttpContext httpContext,
10
        Exception exception,
11
        CancellationToken cancellationToken)
12
    {
13
        logger.LogError(exception, "Unhandled exception occurred. TraceId: {TraceId}",
14
            httpContext.TraceIdentifier);
15

16
        var (statusCode, title) = MapException(exception);
17

18
        httpContext.Response.StatusCode = statusCode;
19

20
        var problemDetails = new ProblemDetails
21
        {
22
            Status = statusCode,
23
            Title = title,
24
            Type = GetProblemType(statusCode),
25
            Instance = httpContext.Request.Path,
26
            Detail = GetSafeErrorMessage(exception, httpContext)
27
        };
28

29
        problemDetails.Extensions["traceId"] = httpContext.TraceIdentifier;
30
        problemDetails.Extensions["timestamp"] = DateTime.UtcNow;
31

32
        return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
33
        {
34
            HttpContext = httpContext,
35
            ProblemDetails = problemDetails
36
        });
37
    }
38

39
    private static (int StatusCode, string Title) MapException(Exception exception) => exception switch
40
    {
41
        AppException appEx => ((int)appEx.StatusCode, appEx.Message),
42
        ArgumentNullException => (StatusCodes.Status400BadRequest, "Invalid argument provided"),
43
        ArgumentException => (StatusCodes.Status400BadRequest, "Invalid argument provided"),
44
        UnauthorizedAccessException => (StatusCodes.Status401Unauthorized, "Unauthorized"),
45
        _ => (StatusCodes.Status500InternalServerError, "An unexpected error occurred")
46
    };
47

48
    private static string GetProblemType(int statusCode) => statusCode switch
49
    {
50
        400 => "https://tools.ietf.org/html/rfc9110#section-15.5.1",
51
        401 => "https://tools.ietf.org/html/rfc9110#section-15.5.2",
52
        403 => "https://tools.ietf.org/html/rfc9110#section-15.5.4",
53
        404 => "https://tools.ietf.org/html/rfc9110#section-15.5.5",
54
        409 => "https://tools.ietf.org/html/rfc9110#section-15.5.10",
55
        _ => "https://tools.ietf.org/html/rfc9110#section-15.6.1"
56
    };
57

58
    private static string? GetSafeErrorMessage(Exception exception, HttpContext context)
59
    {
60
        // Only expose details in development
61
        var env = context.RequestServices.GetRequiredService<IHostEnvironment>();
62
        if (env.IsDevelopment())
63
        {
64
            return exception.Message;
65
        }
66

67
        // In production, only expose messages from our own exceptions
68
        return exception is AppException ? exception.Message : null;
69
    }
70
}

This is the heart of our exception handling. Let me walk you through each part:

Constructor and Dependencies (Lines 4-6)

public sealed class GlobalExceptionHandler(
    ILogger<GlobalExceptionHandler> logger,
    IProblemDetailsService problemDetailsService) : IExceptionHandler

We inject two services:

• ILogger<GlobalExceptionHandler> — For logging exceptions with proper categorization
• IProblemDetailsService — ASP.NET Core’s built-in service for writing RFC 9457-compliant responses. This handles content negotiation, serialization, and ensures consistent formatting.

The TryHandleAsync Method (Lines 8-36)

This is the only method required by IExceptionHandler. It receives three parameters:

• HttpContext httpContext — The current request context, giving us access to the response, request path, and services
• Exception exception — The actual exception that was thrown
• CancellationToken cancellationToken — For handling request cancellation

Lines 13-14: First, we log the exception. Notice we include httpContext.TraceIdentifier — this is crucial for correlating logs with specific requests. When a user reports an error, you can search your logs by this trace ID.

Line 16: We call MapException to determine the appropriate HTTP status code and title. This uses pattern matching to handle different exception types elegantly.

Line 18: We set the response status code. This must happen before writing the response body.

Lines 20-27: We build the ProblemDetails object:

• Status — The HTTP status code (400, 404, 500, etc.)
• Title — A short, human-readable summary
• Type — A URI reference to documentation about this error type (RFC 9110 references)
• Instance — The specific request path that caused the error
• Detail — Additional information (only in development or for safe exceptions)

Lines 29-30: We add custom extensions to the problem details. traceId helps with debugging, and timestamp records when the error occurred. These appear in the JSON response.

Lines 32-36: Instead of manually serializing JSON, we use IProblemDetailsService.TryWriteAsync. This service:

• Handles content negotiation (respects Accept headers)
• Applies any global customizations from AddProblemDetails()
• Returns true if it successfully wrote the response, false otherwise

Exception Mapping (Lines 39-46)

private static (int StatusCode, string Title) MapException(Exception exception) => exception switch
{
    AppException appEx => ((int)appEx.StatusCode, appEx.Message),
    ArgumentNullException => (StatusCodes.Status400BadRequest, "Invalid argument provided"),
    // ...
};

This switch expression maps exceptions to HTTP responses:

• AppException (our custom base) — Uses the status code embedded in the exception itself
• ArgumentNullException and ArgumentException — Map to 400 Bad Request
• UnauthorizedAccessException — Maps to 401 Unauthorized
• Everything else — Defaults to 500 Internal Server Error

Safe Error Messages (Lines 58-69)

private static string? GetSafeErrorMessage(Exception exception, HttpContext context)
{
    var env = context.RequestServices.GetRequiredService<IHostEnvironment>();
    if (env.IsDevelopment())
    {
        return exception.Message;
    }
    return exception is AppException ? exception.Message : null;
}

This is a security-critical method. In development, we show the full exception message for debugging. In production:

• For AppException types (our own exceptions), we show the message — we control these and know they’re safe
• For system exceptions, we return null — never expose internal error details like “Connection string not found” or SQL errors

Registration in Program.cs

1
var builder = WebApplication.CreateBuilder(args);
2

3
builder.Services.AddProblemDetails();
4
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
5

6
var app = builder.Build();
7

8
app.UseExceptionHandler();
9

10
app.Run();

• Line 3: AddProblemDetails() registers IProblemDetailsService and related services. Without this, our handler can’t use the problem details service.
• Line 4: AddExceptionHandler<GlobalExceptionHandler>() registers our handler as a singleton in the DI container.
• Line 8: UseExceptionHandler() adds the exception handling middleware to the pipeline. This middleware catches exceptions and delegates to our registered handlers.

That’s it. Clean, maintainable, and production-ready.

What’s New in .NET 10: SuppressDiagnosticsCallback

.NET 10 introduces a significant change to how the exception handling middleware logs errors. Previously, in .NET 8 and 9, the middleware would always emit diagnostic logs (at Error level) for every exception — even if your IExceptionHandler already handled it.

This was annoying. You’d end up with duplicate logs: one from your handler and one from the middleware.

.NET 10 changes the default behavior: When your IExceptionHandler.TryHandleAsync returns true, the middleware no longer emits diagnostics by default. This makes more sense — if you handled the exception, you probably logged it yourself.

Controlling Diagnostic Output

If you need the old behavior or want fine-grained control, use SuppressDiagnosticsCallback:

1
// Revert to .NET 8/9 behavior - always emit diagnostics
2
app.UseExceptionHandler(new ExceptionHandlerOptions
3
{
4
    SuppressDiagnosticsCallback = _ => false
5
});
6

7
// Suppress diagnostics only for specific exception types
8
app.UseExceptionHandler(new ExceptionHandlerOptions
9
{
10
    SuppressDiagnosticsCallback = context =>
11
        context.Exception is NotFoundException or BadRequestException
12
});

Let me explain both scenarios:

Lines 1-5 (Revert to old behavior): The callback receives an ExceptionHandlerContext but we ignore it (using _) and always return false. Returning false means “don’t suppress diagnostics” — so the middleware will log every exception, just like .NET 8/9 did.

Lines 7-12 (Selective suppression): Here we check the exception type. If it’s a NotFoundException or BadRequestException, we return true (suppress diagnostics). For all other exceptions, we return false (emit diagnostics). This is useful when you want to log unexpected errors at the middleware level but skip logging for expected business errors that you’re already handling in your IExceptionHandler.

This is useful when:

• You have transient exceptions that don’t need to clutter your logs
• You want middleware-level logging for some exceptions but not others
• You’re migrating from .NET 9 and need consistent logging behavior during the transition

Chaining Multiple Exception Handlers

One of the most powerful features of IExceptionHandler is the ability to chain multiple handlers. Each handler can decide whether to handle the exception or pass it to the next one.

1
public sealed class NotFoundExceptionHandler(ILogger<NotFoundExceptionHandler> logger) : IExceptionHandler
2
{
3
    public async ValueTask<bool> TryHandleAsync(
4
        HttpContext httpContext,
5
        Exception exception,
6
        CancellationToken cancellationToken)
7
    {
8
        if (exception is not NotFoundException notFound)
9
        {
10
            return false; // Let the next handler try
11
        }
12

13
        logger.LogWarning("Resource not found: {Message}", notFound.Message);
14

15
        httpContext.Response.StatusCode = StatusCodes.Status404NotFound;
16
        await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
17
        {
18
            Status = 404,
19
            Title = "Resource Not Found",
20
            Detail = notFound.Message
21
        }, cancellationToken);
22

23
        return true; // We handled it
24
    }
25
}

Here’s the key pattern:

• Lines 8-10: The guard clause is the most important part. We check if the exception is NotFoundException. If it’s NOT, we immediately return false. This tells the middleware: “I can’t handle this, try the next handler.”
• Line 13: We log at Warning level, not Error. A 404 isn’t an error in your system — it’s a valid response for a missing resource. This keeps your error logs clean.
• Lines 15-21: We write the response directly using WriteAsJsonAsync. Notice we pass the cancellationToken — always do this to support request cancellation.
• Line 23: Returning true tells the middleware: “I handled this, stop looking for other handlers.”

Here’s another handler for validation errors:

1
public sealed class ValidationExceptionHandler(ILogger<ValidationExceptionHandler> logger) : IExceptionHandler
2
{
3
    public async ValueTask<bool> TryHandleAsync(
4
        HttpContext httpContext,
5
        Exception exception,
6
        CancellationToken cancellationToken)
7
    {
8
        if (exception is not ValidationException validation)
9
        {
10
            return false;
11
        }
12

13
        logger.LogWarning("Validation failed: {Message}", validation.Message);
14

15
        httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
16
        await httpContext.Response.WriteAsJsonAsync(new ValidationProblemDetails
17
        {
18
            Status = 400,
19
            Title = "Validation Failed",
20
            Errors = validation.Errors
21
        }, cancellationToken);
22

23
        return true;
24
    }
25
}

• Lines 8-10: Same pattern — check if it’s our exception type, return false if not.
• Lines 16-20: We use ValidationProblemDetails instead of regular ProblemDetails. This subclass includes an Errors dictionary that maps field names to error messages — perfect for form validation.

Registration Order Matters

1
builder.Services.AddExceptionHandler<NotFoundExceptionHandler>();
2
builder.Services.AddExceptionHandler<ValidationExceptionHandler>();
3
builder.Services.AddExceptionHandler<GlobalExceptionHandler>(); // Fallback

The handlers execute in registration order:

1. Line 1: NotFoundExceptionHandler runs first. If the exception is NotFoundException, it handles it and returns true. Otherwise, returns false.
2. Line 2: ValidationExceptionHandler runs next. Same pattern — handles ValidationException or passes along.
3. Line 3: GlobalExceptionHandler is the fallback. It should handle ALL exceptions (never return false) because it’s the last line of defense.

This pattern keeps each handler focused on one exception type, making them easy to test and maintain. You can add or remove handlers without touching the others.

Silencing Built-in Middleware Logs

Even in .NET 10, you might want to silence the default logs from Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware. Add this to your appsettings.json:

1
{
2
  "Logging": {
3
    "LogLevel": {
4
      "Default": "Information",
5
      "Microsoft.AspNetCore": "Warning",
6
      "Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware": "None"
7
    }
8
  }
9
}

Line 6 is the key. By setting the log level to None for the middleware’s specific namespace, you completely disable its logging output. The middleware still functions — it catches exceptions and calls your handlers — but it won’t write to your logs.

Why would you want this?

• Your IExceptionHandler already logs the exception with your preferred format and log level
• You don’t want duplicate entries cluttering your observability platform
• You have specific logging requirements that the middleware doesn’t meet

This ensures you only see logs from your handlers, not duplicate middleware logs.

Complete Working Example

Let’s put it all together with a minimal, single-file example. This is great for learning and quick prototypes — you can copy-paste it into a new .NET 10 project and run it immediately. For production applications, see the Production-Ready Project Structure section below where we organize this into proper folders.

1
using Microsoft.AspNetCore.Diagnostics;
2
using Microsoft.AspNetCore.Mvc;
3
using System.Net;
4

5
var builder = WebApplication.CreateBuilder(args);
6

7
builder.Services.AddProblemDetails(options =>
8
{
9
    options.CustomizeProblemDetails = ctx =>
10
    {
11
        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
12
        ctx.ProblemDetails.Extensions["timestamp"] = DateTime.UtcNow;
13
        ctx.ProblemDetails.Instance = $"{ctx.HttpContext.Request.Method} {ctx.HttpContext.Request.Path}";
14
    };
15
});
16

17
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
18

19
builder.Services.AddOpenApi();
20

21
var app = builder.Build();
22

23
app.UseExceptionHandler();
24

25
app.MapOpenApi();
26

27
// Test endpoints
28
app.MapGet("/", () => "Global Exception Handling Demo - .NET 10");
29

30
app.MapGet("/products/{id:guid}", (Guid id) =>
31
{
32
    // Simulate not found
33
    throw new NotFoundException("Product", id);
34
});
35

36
app.MapPost("/products", (ProductRequest request) =>
37
{
38
    if (string.IsNullOrWhiteSpace(request.Name))
39
    {
40
        throw new BadRequestException("Product name is required");
41
    }
42
    return Results.Created($"/products/{Guid.NewGuid()}", request);
43
});
44

45
app.MapGet("/error", () =>
46
{
47
    // Simulate unexpected error
48
    throw new InvalidOperationException("Something went terribly wrong!");
49
});
50

51
app.Run();
52

53
// Records and Exceptions
54
public record ProductRequest(string Name, decimal Price);
55

56
public abstract class AppException(string message, HttpStatusCode statusCode = HttpStatusCode.InternalServerError)
57
    : Exception(message)
58
{
59
    public HttpStatusCode StatusCode { get; } = statusCode;
60
}
61

62
public sealed class NotFoundException(string resourceName, object key)
63
    : AppException($"{resourceName} with identifier '{key}' was not found.", HttpStatusCode.NotFound);
64

65
public sealed class BadRequestException(string message)
66
    : AppException(message, HttpStatusCode.BadRequest);
67

68
// Exception Handler
69
public sealed class GlobalExceptionHandler(
70
    ILogger<GlobalExceptionHandler> logger,
71
    IProblemDetailsService problemDetailsService) : IExceptionHandler
72
{
73
    public async ValueTask<bool> TryHandleAsync(
74
        HttpContext httpContext,
75
        Exception exception,
76
        CancellationToken cancellationToken)
77
    {
78
        logger.LogError(exception, "Exception occurred. TraceId: {TraceId}", httpContext.TraceIdentifier);
79

80
        var (statusCode, title) = exception switch
81
        {
82
            AppException appEx => ((int)appEx.StatusCode, appEx.Message),
83
            _ => (StatusCodes.Status500InternalServerError, "An unexpected error occurred")
84
        };
85

86
        httpContext.Response.StatusCode = statusCode;
87

88
        return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
89
        {
90
            HttpContext = httpContext,
91
            ProblemDetails = new ProblemDetails
92
            {
93
                Status = statusCode,
94
                Title = title
95
            }
96
        });
97
    }
98
}

Code Walkthrough

Lines 7-15 (Global ProblemDetails Customization):

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
        ctx.ProblemDetails.Extensions["timestamp"] = DateTime.UtcNow;
        ctx.ProblemDetails.Instance = $"{ctx.HttpContext.Request.Method} {ctx.HttpContext.Request.Path}";
    };
});

This configures all ProblemDetails responses globally — not just from our exception handler, but also from Results.Problem(), validation errors, and status code pages. Every error response will automatically include the trace ID, timestamp, and request path.

Line 17: Registers our exception handler. Remember, it’s a singleton — one instance handles all requests.

Line 23: Adds the exception handling middleware to the pipeline. This must come early — before your endpoints — so it can catch exceptions from anywhere downstream.

Lines 30-34 (Not Found Endpoint):

app.MapGet("/products/{id:guid}", (Guid id) =>
{
    throw new NotFoundException("Product", id);
});

This endpoint always throws NotFoundException. In a real app, you’d fetch from a database and throw only if the product doesn’t exist. The exception bubbles up, gets caught by our handler, and returns a 404 with proper ProblemDetails.

Lines 36-43 (Validation Example):

app.MapPost("/products", (ProductRequest request) =>
{
    if (string.IsNullOrWhiteSpace(request.Name))
    {
        throw new BadRequestException("Product name is required");
    }
    return Results.Created($"/products/{Guid.NewGuid()}", request);
});

A simple validation — if the name is empty, throw BadRequestException. This returns a 400 with a clear error message.

Lines 45-49 (Unexpected Error):

app.MapGet("/error", () =>
{
    throw new InvalidOperationException("Something went terribly wrong!");
});

This simulates an unexpected error — something you didn’t anticipate. The handler catches it, returns 500, and does not expose the internal message in production.

When you call GET /products/{some-guid}, you’ll get:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Product with identifier 'some-guid' was not found.",
  "status": 404,
  "instance": "GET /products/some-guid",
  "traceId": "0HN123ABC:00000001",
  "timestamp": "2026-01-21T10:30:00.000Z"
}

Here’s what a validation error looks like in Scalar when you POST to /products with an empty name:

Isn’t that clean?

Production-Ready Project Structure

The single-file example above is great for learning, but in production you’ll want a proper folder structure. Here’s the recommended layout for organizing your exception handling code:

YourApi/
├── Exceptions/
│   ├── AppException.cs
│   ├── NotFoundException.cs
│   ├── BadRequestException.cs
│   ├── ConflictException.cs
│   └── ValidationException.cs
├── Handlers/
│   ├── GlobalExceptionHandler.cs
│   ├── NotFoundExceptionHandler.cs      # Optional - for handler chaining
│   └── ValidationExceptionHandler.cs    # Optional - for handler chaining
├── Program.cs
├── appsettings.json
└── appsettings.Development.json

Exception Classes in Separate Files

Each exception should live in its own file under the Exceptions/ folder. Here’s the production version using primary constructors:

Exceptions/AppException.cs

using System.Net;

namespace YourApi.Exceptions;

public abstract class AppException(string message, HttpStatusCode statusCode = HttpStatusCode.InternalServerError)
    : Exception(message)
{
    public HttpStatusCode StatusCode { get; } = statusCode;
}

Exceptions/NotFoundException.cs

using System.Net;

namespace YourApi.Exceptions;

public sealed class NotFoundException(string resourceName, object key)
    : AppException($"{resourceName} with identifier '{key}' was not found.", HttpStatusCode.NotFound);

Exceptions/BadRequestException.cs

using System.Net;

namespace YourApi.Exceptions;

public sealed class BadRequestException(string message)
    : AppException(message, HttpStatusCode.BadRequest);

Exceptions/ConflictException.cs

using System.Net;

namespace YourApi.Exceptions;

public sealed class ConflictException(string message)
    : AppException(message, HttpStatusCode.Conflict);

Exceptions/ValidationException.cs

using System.Net;

namespace YourApi.Exceptions;

public sealed class ValidationException : AppException
{
    public IDictionary<string, string[]> Errors { get; }

    public ValidationException(IDictionary<string, string[]> errors)
        : base("One or more validation errors occurred.", HttpStatusCode.BadRequest)
    {
        Errors = errors;
    }

    public ValidationException(string field, string error)
        : base("One or more validation errors occurred.", HttpStatusCode.BadRequest)
    {
        Errors = new Dictionary<string, string[]>
        {
            { field, [error] }
        };
    }
}

Full GlobalExceptionHandler Implementation

Here’s the production-ready handler with all helper methods in its own file:

Handlers/GlobalExceptionHandler.cs

using YourApi.Exceptions;
using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;

namespace YourApi.Handlers;

public sealed class GlobalExceptionHandler(
    ILogger<GlobalExceptionHandler> logger,
    IProblemDetailsService problemDetailsService) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        logger.LogError(exception, "Unhandled exception occurred. TraceId: {TraceId}",
            httpContext.TraceIdentifier);

        var (statusCode, title) = MapException(exception);

        httpContext.Response.StatusCode = statusCode;

        var problemDetails = new ProblemDetails
        {
            Status = statusCode,
            Title = title,
            Type = GetProblemType(statusCode),
            Instance = httpContext.Request.Path,
            Detail = GetSafeErrorMessage(exception, httpContext)
        };

        problemDetails.Extensions["traceId"] = httpContext.TraceIdentifier;
        problemDetails.Extensions["timestamp"] = DateTime.UtcNow;

        return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = httpContext,
            ProblemDetails = problemDetails
        });
    }

    private static (int StatusCode, string Title) MapException(Exception exception) => exception switch
    {
        AppException appEx => ((int)appEx.StatusCode, appEx.Message),
        ArgumentNullException => (StatusCodes.Status400BadRequest, "Invalid argument provided"),
        ArgumentException => (StatusCodes.Status400BadRequest, "Invalid argument provided"),
        UnauthorizedAccessException => (StatusCodes.Status401Unauthorized, "Unauthorized"),
        _ => (StatusCodes.Status500InternalServerError, "An unexpected error occurred")
    };

    private static string GetProblemType(int statusCode) => statusCode switch
    {
        400 => "https://tools.ietf.org/html/rfc9110#section-15.5.1",
        401 => "https://tools.ietf.org/html/rfc9110#section-15.5.2",
        403 => "https://tools.ietf.org/html/rfc9110#section-15.5.4",
        404 => "https://tools.ietf.org/html/rfc9110#section-15.5.5",
        409 => "https://tools.ietf.org/html/rfc9110#section-15.5.10",
        _ => "https://tools.ietf.org/html/rfc9110#section-15.6.1"
    };

    private static string? GetSafeErrorMessage(Exception exception, HttpContext context)
    {
        var env = context.RequestServices.GetRequiredService<IHostEnvironment>();
        if (env.IsDevelopment())
        {
            return exception.Message;
        }
        return exception is AppException ? exception.Message : null;
    }
}

Clean Program.cs

With the handlers in separate files, your Program.cs stays clean and focused:

using YourApi.Handlers;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
        ctx.ProblemDetails.Extensions["timestamp"] = DateTime.UtcNow;
        ctx.ProblemDetails.Instance = $"{ctx.HttpContext.Request.Method} {ctx.HttpContext.Request.Path}";
    };
});

// Register exception handlers (order matters for chaining)
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

builder.Services.AddOpenApi();

var app = builder.Build();

app.UseExceptionHandler();

app.MapOpenApi();
app.MapScalarApiReference(); // API docs at /scalar/v1

// Your endpoints here...

app.Run();

Note: We’re using Scalar for API documentation instead of Swagger. It’s cleaner, faster, and works great with .NET 10’s built-in OpenAPI support.

Get the Complete Sample Code

The full production-ready sample with all exception types, handlers, and test endpoints is available on GitHub:

👉 Download the complete source code

Clone it and run it locally:

git clone https://github.com/codewithmukesh/dotnet-webapi-zero-to-hero-course.git
cd dotnet-webapi-zero-to-hero-course/modules/01-getting-started/global-exception-handling
dotnet run --project GlobalExceptionHandling.Api

Then navigate to http://localhost:5000/scalar/v1 to explore the API and test the exception handling endpoints.

Performance Consideration: The Result Pattern

I should mention this because exceptions aren’t free. As David Fowler (Microsoft’s ASP.NET Core architect) points out, exceptions are expensive in terms of performance. They involve stack unwinding, memory allocation, and can significantly impact throughput under load.

For expected error conditions (like validation failures or not-found scenarios), consider using the Result pattern instead:

1
public record Result<T>
2
{
3
    public T? Value { get; init; }
4
    public string? Error { get; init; }
5
    public bool IsSuccess => Error is null;
6

7
    public static Result<T> Success(T value) => new() { Value = value };
8
    public static Result<T> Failure(string error) => new() { Error = error };
9
}
10

11
// Usage
12
public Result<Product> GetById(Guid id)
13
{
14
    var product = _repository.Find(id);
15
    return product is not null
16
        ? Result<Product>.Success(product)
17
        : Result<Product>.Failure($"Product {id} not found");
18
}

Let me break this down:

• Lines 1-9 (Result Record): This is a simple discriminated union. A Result<T> either has a Value (success) or an Error message (failure), never both. The IsSuccess property checks if there’s no error.
• Line 7: Factory method for successful results — wraps the value.
• Line 8: Factory method for failures — stores the error message.
• Lines 12-18 (Usage): Instead of throwing NotFoundException, we return Result<Product>.Failure(...). The caller checks IsSuccess and handles accordingly.

The advantage? No stack unwinding, no expensive exception objects. Just a simple record allocation. Under high load, this can make a noticeable difference.

In your endpoint, you’d handle it like this:

app.MapGet("/products/{id:guid}", (Guid id, ProductService service) =>
{
    var result = service.GetById(id);
    return result.IsSuccess
        ? Results.Ok(result.Value)
        : Results.NotFound(result.Error);
});

Use exceptions for truly exceptional situations — things that shouldn’t happen during normal operation (database connection lost, file system errors, external service failures). Use the Result pattern for expected business failures (not found, validation errors, insufficient permissions).

Frequently Asked Questions

Summary

Global exception handling is essential for building robust ASP.NET Core applications. Here’s what we covered:

• Try-catch blocks are not suitable for global handling — too repetitive and inconsistent
• Custom middleware works but is now outdated for .NET 8+ projects
• IExceptionHandler is the modern, recommended approach — clean, testable, and chainable
• .NET 10 introduces SuppressDiagnosticsCallback to control diagnostic output
• Use IProblemDetailsService for RFC 9457-compliant error responses
• Chain multiple handlers for different exception types
• Consider the Result pattern for expected failures to avoid performance overhead
• Organize your code with a proper folder structure for production applications

👉 Get the complete source code on GitHub — clone it, run it, and use it as a starting point for your projects.

If you found this guide helpful, share it with your team. Building consistent error handling from day one saves countless debugging hours down the road.

Happy Coding :)