Driver FixRecommendedSound, Wi-Fi or graphics acting up? Check drivers firstFind missing or outdated drivers fast.Check DriversOctober DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run Scan×
Skip to content
World desk3 min

Exception Handling in ASP.NET Core: Development, Production, and APIs

Use development-only diagnostics, configure a safe production fallback, and choose centralized handlers or Problem Details to meet your ASP.NET Core API’s response contract.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

In ASP.NET Core, use the Developer Exception Page for development diagnostics and configure production middleware to return safe, deliberate error responses. For APIs, AddProblemDetails can provide a consistent machine-readable format; use IExceptionHandler when known exception types need centralized, specific handling.

Choose the right exception-handling approach

The right setup depends on who will see the response, whether the error is expected, and whether your application must follow a particular API contract.

As an Amazon Associate I earn from qualifying purchases.

  • Development diagnostics: use the Developer Exception Page while developing locally.
  • Production fallback: use UseExceptionHandler to catch unhandled exceptions and return a safe fallback response.
  • Known exception types: implement one or more IExceptionHandler services to map specific exceptions to responses.
  • API error bodies: register AddProblemDetails when Problem Details fits your public response contract.

These approaches can work together: exception-specific handlers can run before a configured fallback, while the fallback handles exceptions that no specific handler claims.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use detailed exception output only in development

The Developer Exception Page captures synchronous and asynchronous exceptions thrown by later middleware and displays diagnostic information. Current WebApplication.CreateBuilder templates enable it in the Development environment. Microsoft cautions against exposing it in Production: its output may include stack traces, query values, cookies, headers, and endpoint metadata. The page may not contain complete diagnostic information, so use logging when you need a fuller record. Microsoft’s ASP.NET Core error-handling guidance

Configure a production fallback with UseExceptionHandler

UseExceptionHandler catches and logs unhandled exceptions. A common page-based fallback is UseExceptionHandler("/Error"). When the response has not started, path-based handling re-executes the request through the alternate pipeline at the configured path. If that alternate pipeline also throws, the middleware rethrows the original exception.

If an error page is not appropriate, configure a fallback handler or Problem Details instead. Calling UseExceptionHandler() with neither a path nor an inline handler requires fallback configuration such as AddProblemDetails; without it, startup configuration fails. Registered IExceptionHandler implementations run before the fallback. Microsoft’s ASP.NET Core error-handling guidance

Handle known exceptions centrally with IExceptionHandler

Implement IExceptionHandler.TryHandleAsync(HttpContext, Exception, CancellationToken) for centralized, exception-specific handling. Register each implementation with AddExceptionHandler<T>, then add exception-handling middleware with UseExceptionHandler. Registration alone does not activate the handlers. The interface applies to ASP.NET Core 8.0, 9.0, and 10.0. Microsoft’s IExceptionHandler API reference

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Understand handler order and return values

Handlers are singleton services and run in registration order. A handler returning false passes the exception to the next handler or the configured fallback. A handler returning true stops the chain and takes responsibility for the complete response, including its status code and body.

Do not treat true as meaning the middleware will finish the response for you. If a handled response has no status or body, it can become a 404 and trigger a middleware log. Set a deliberate status and write the response, or use IProblemDetailsService to create a suitable body. Microsoft’s ASP.NET Core error-handling guidance

Return Problem Details from APIs

AddProblemDetails registers ASP.NET Core’s default IProblemDetailsService. Exception-handling middleware can use it to generate Problem Details when no custom handler handles the exception; status-code pages can also provide a body for otherwise bodyless 4xx and 5xx responses. Problem Details is a commonly used HTTP API error format, not a requirement for every API. Choose it when it matches your API contract, and keep implementation details and sensitive data out of public responses. Microsoft’s API error-handling guidance

Check content negotiation

The default Problem Details writer supports application/json. Generation depends on the request’s Accept header matching a supported writer content type; an Accept header that excludes supported types can prevent a Problem Details body from being generated. If your API contract requires another format, customize the service or add a writer for that format. Microsoft’s API error-handling guidance

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Account for .NET 10 exception diagnostics

In .NET 10, an exception reported as handled by an IExceptionHandler no longer produces diagnostics by default. If you rely on the .NET 8 or .NET 9 behavior, set SuppressDiagnosticsCallback = _ => false to restore it. You can also suppress diagnostics conditionally according to the exception or request context. Review this behavior when upgrading if your monitoring depends on middleware diagnostics for handled exceptions. Microsoft’s .NET 10 breaking-change note

Quick Recap

Bestseller No. 2
SaleBestseller No. 5
Programming ASP.NET Core (Developer Reference)
Programming ASP.NET Core (Developer Reference)
Integrating ASP.NET Core with leading client-side frameworks, including Bootstrap; ASP.NET Core code for implementing business logic and data transformations
$24.99
Best Value
Sale
Programming ASP.NET Core (Developer Reference)
  • Applying all key ASP.NET Core components, including MVC for HTML generation, .NET Core, EF Core, ASP.NET Identity, dependency injection, and more
  • Integrating ASP.NET Core with leading client-side frameworks, including Bootstrap
  • ASP.NET Core code for implementing business logic and data transformations
  • Handling configuration, routing, controllers, views, and common tasks (including posting forms and presenting data)
  • Performing complementary tasks: error handling, logging, application design, authentication, localization, and more

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.