ErrorLens.ErrorHandling 1.4.0

ErrorLens.ErrorHandling

Transform unhandled exceptions into clean, structured JSON responses with minimal setup — just two lines of code to get started.

ErrorLens provides a production-ready error handling pipeline for ASP.NET Core APIs. Every exception is automatically converted into a consistent, structured JSON response with appropriate HTTP status codes, machine-readable error codes, and human-readable messages. The library handles the full lifecycle from exception to response: handler selection, response customization, secure 5xx safe messaging, configurable logging, and optional localization — with zero-config defaults that work out of the box and deep extensibility when you need it.

Full documentation: https://ahmedv20.github.io/error-handling-dotnet/current/

Features

• Zero-Config Exception Handling — Unhandled exceptions return structured JSON error responses out of the box
• Validation Error Details — Field-level errors with property names, messages, and rejected values
• Secure Error Responses — 5xx errors return generic safe messages to prevent information disclosure
• Custom JSON Field Names — Rename any response field (code → type, message → detail, etc.)
• YAML & JSON Configuration — Configure error codes, messages, HTTP statuses via appsettings.json or errorhandling.yml
• Custom Exception Attributes — [ResponseErrorCode], [ResponseStatus], [ResponseErrorProperty]
• Custom Exception Handlers — Register IApiExceptionHandler implementations with priority ordering
• AggregateException Unwrapping — Automatically flattens and unwraps single-inner AggregateException
• Response Customization — Add global properties (traceId, timestamp) via IApiErrorResponseCustomizer
• Replaceable Mappers — Override IErrorCodeMapper, IErrorMessageMapper, or IHttpStatusMapper
• RFC 9457 Problem Details — Opt-in application/problem+json compliant responses
• Configurable Logging — Control log levels and stack trace verbosity per HTTP status code
• Startup Validation — JSON field names validated at startup (non-null, non-empty, unique)
• Multi-Target Support — .NET 6.0, 7.0, 8.0, 9.0, and 10.0
• .NET 8+ Native Integration — Automatically registers IExceptionHandler on .NET 8+; falls back to middleware on .NET 6/7
• OpenTelemetry Tracing — Automatic Activity spans with error tags and OTel semantic conventions
• Error Message Localization — IErrorMessageLocalizer with IStringLocalizer bridge for multi-language support
• OpenAPI / Swagger Integration — Auto-add error response schemas to API docs
• Rate Limiting — Structured 429 responses with Retry-After headers via IRateLimitResponseWriter (.NET 7+)
• Built-in Error Code Constants — DefaultErrorCodes class with 23 predefined codes for consistent frontend matching
• FluentValidation Integration — First-party support for FluentValidation with automatic error code mapping and severity filtering
• Configurable Error Messages — Customize 5xx fallback message and override built-in handler messages via FallbackMessage and BuiltInMessages
• 5 Error Code Strategies — AllCaps, FullQualifiedName, KebabCase, PascalCase, DotSeparated

Quick Start

Installation

dotnet add package ErrorLens.ErrorHandling

Minimal API (.NET 6+)

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddErrorHandling();

var app = builder.Build();
app.UseErrorHandling();

app.MapGet("/", () => { throw new Exception("Something went wrong"); });
app.Run();

Controller-Based API

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddErrorHandling();

var app = builder.Build();
app.UseErrorHandling();
app.MapControllers();
app.Run();

With Configuration Options

// Option 1: Inline options
builder.Services.AddErrorHandling(options =>
{
    options.HttpStatusInJsonResponse = true;
    options.OverrideModelStateValidation = true;
    options.IncludeRejectedValues = true;
    options.ExceptionLogging = ExceptionLogging.WithStacktrace;
});

// Option 2: Bind from appsettings.json / YAML
builder.Services.AddErrorHandling(builder.Configuration);

Note (.NET 8+): ErrorLens automatically registers IExceptionHandler on .NET 8+, so exceptions are handled natively by the ASP.NET Core exception handler pipeline. On .NET 6/7, UseErrorHandling() registers middleware instead. Both paths produce identical results.

All unhandled exceptions now return structured JSON:

{
  "code": "INVALID_OPERATION",
  "message": "The operation is not valid."
}

The error code is generated automatically from the exception class name using ALL_CAPS strategy — InvalidOperationException becomes INVALID_OPERATION, UserNotFoundException becomes USER_NOT_FOUND.

How It Works

ErrorLens processes exceptions through a pipeline with clearly defined stages:

Exception thrown
  → Handler Selection (sorted by Order, first CanHandle() match wins)
    → Fallback Handler (if no handler matches)
      → HTTP Status in JSON (if configured)
        → Response Customizers (all IApiErrorResponseCustomizer run in order)
          → Logging (ILoggingService with ILoggingFilter checks)
            → Localization (IErrorMessageLocalizer replaces messages)
              → OpenTelemetry (Activity enriched with error tags)
                → JSON Response (or Problem Details if enabled)

Each stage is independently configurable and replaceable. If any handler or customizer throws, the pipeline catches the error, logs both exceptions, and returns a safe 500 response to prevent cascading failures.

For a detailed architecture overview with Mermaid diagrams, see docs/ARCHITECTURE.md.

Packages

Package	Description	Target Frameworks	Version
ErrorLens.ErrorHandling	Core middleware for structured error responses	.NET 6, 7, 8, 9, 10
ErrorLens.ErrorHandling.OpenApi	OpenAPI schema generation (.NET 9+)	.NET 9, 10
ErrorLens.ErrorHandling.Swashbuckle	Swashbuckle integration (.NET 6-8)	.NET 6, 7, 8
ErrorLens.ErrorHandling.FluentValidation	FluentValidation integration	.NET 6, 7, 8, 9, 10

# Optional integration packages
dotnet add package ErrorLens.ErrorHandling.OpenApi        # .NET 9+
dotnet add package ErrorLens.ErrorHandling.Swashbuckle    # .NET 6-8
dotnet add package ErrorLens.ErrorHandling.FluentValidation  # .NET 6-10

Default HTTP Status Mappings

ErrorLens maps common .NET exception types to appropriate HTTP status codes out of the box:

Note: TaskCanceledException inherits from OperationCanceledException, so it also maps to 499 automatically.

Override any mapping via configuration or [ResponseStatus] attributes.

Configuration

ErrorLens supports both JSON (appsettings.json) and YAML (errorhandling.yml) configuration. Here is a minimal example:

{
  "ErrorHandling": {
    "HttpStatusInJsonResponse": true,
    "OverrideModelStateValidation": true,
    "IncludeRejectedValues": true,
    "ExceptionLogging": "WithStacktrace",
    "HttpStatuses": {
      "MyApp.UserNotFoundException": 404
    },
    "Codes": {
      "MyApp.UserNotFoundException": "USER_NOT_FOUND"
    }
  }
}

For YAML configuration:

ErrorHandling:
  HttpStatusInJsonResponse: true
  OverrideModelStateValidation: true
  IncludeRejectedValues: true
  ExceptionLogging: WithStacktrace
  HttpStatuses:
    MyApp.UserNotFoundException: 404
  Codes:
    MyApp.UserNotFoundException: USER_NOT_FOUND

builder.Configuration.AddYamlErrorHandling("errorhandling.yml");
builder.Services.AddErrorHandling(builder.Configuration);

Settings are resolved in this order (highest priority first):

1. Custom exception handlers — IApiExceptionHandler implementations
2. Inline options — Action<ErrorHandlingOptions> in AddErrorHandling()
3. Configuration binding — appsettings.json or errorhandling.yml
4. Exception attributes — [ResponseErrorCode], [ResponseStatus]
5. Default conventions — class name to ALL_CAPS, built-in HTTP status mappings

For the full configuration reference (all options, JSON field names, rate limiting, OpenAPI), see the Configuration Guide.

Exception Attributes

Decorate exception classes with attributes to control error responses declaratively:

[ResponseErrorCode("USER_NOT_FOUND")]
[ResponseStatus(HttpStatusCode.NotFound)]
public class UserNotFoundException : Exception
{
    [ResponseErrorProperty("userId")]
    public string UserId { get; }

    public UserNotFoundException(string userId)
        : base($"User {userId} not found") => UserId = userId;
}

Response:

{
  "code": "USER_NOT_FOUND",
  "message": "User abc-123 not found",
  "userId": "abc-123"
}

For more details, see Exception Attributes.

Validation Errors

Enable OverrideModelStateValidation to get structured field-level validation errors:

builder.Services.AddErrorHandling(options =>
{
    options.OverrideModelStateValidation = true;
});

Response:

{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "fieldErrors": [
    {
      "code": "INVALID_EMAIL",
      "property": "email",
      "message": "Invalid email format",
      "rejectedValue": "bad",
      "path": "email"
    }
  ]
}

Validation error codes and messages can be customized via configuration. See the Configuration Guide for details.

Security

All 5xx-class errors (500-599) automatically return a generic safe message instead of the raw exception message. The default message can be customized via ErrorHandlingOptions.FallbackMessage:

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}

This prevents internal details (database connection strings, file paths, stack traces) from leaking to API consumers. The original exception is still logged with full details on the server side. The BadRequestExceptionHandler also sanitizes Kestrel-internal error messages automatically.

Samples

Documentation

Documentation site: https://ahmedv20.github.io/error-handling-dotnet/current/

Guides

• Getting Started — Installation, setup, first error response
• Configuration — JSON/YAML config, all options, priority order
• Logging — Log levels, stack traces, logging filters
• Troubleshooting — Common issues and solutions

Core Features

• Exception Attributes — [ResponseErrorCode], [ResponseStatus], [ResponseErrorProperty]
• Custom Handlers — IApiExceptionHandler, IFallbackApiExceptionHandler
• Response Customization — IApiErrorResponseCustomizer
• JSON Field Names — Rename any response field
• Problem Details (RFC 9457) — application/problem+json format

Integration Features

• OpenTelemetry Tracing — Automatic Activity spans
• Localization — Multi-language error messages
• OpenAPI (.NET 9+) — Auto-generated error schemas
• Swashbuckle (.NET 6-8) — Swagger error schemas
• Rate Limiting (.NET 7+) — Structured 429 responses
• FluentValidation — FluentValidation integration with automatic error mapping

Reference

• Architecture — Full architecture guide with Mermaid diagrams
• API Reference — All public types, interfaces, and extension methods
• Changelog — Version history

Prerequisites

• .NET SDK 6.0 or later (multi-targeting builds require .NET 10.0 SDK)
• ASP.NET Core application (Minimal API or Controller-based)

Building from Source

git clone https://github.com/AhmedV20/error-handling-dotnet.git
cd error-handling-dotnet
dotnet restore
dotnet build

Running Tests

dotnet test

Running Sample Projects

dotnet run --project samples/MinimalApiSample
dotnet run --project samples/ShowcaseSample

🤝 Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.