ln-772-error-handler-setup

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-770-crosscutting-setup

Configures global error handling for .NET and Python backend applications.

---

Overview

Aspect	Details
Input	Context Store from ln-770
Output	Exception handling middleware and custom exceptions
Stacks	.NET (ASP.NET Core Middleware), Python (FastAPI exception handlers)

---

Phase 1: Receive Context

Accept Context Store from coordinator.

Required Context:

• STACK: .NET or Python
• FRAMEWORK: ASP.NET Core or FastAPI
• PROJECT_ROOT: Project directory path
• ENVIRONMENT: Development or Production

Idempotency Check:

• .NET: Grep for GlobalExceptionMiddleware or UseExceptionHandler
• Python: Grep for @app.exception_handler or exception_handlers.py
• If found: Return { "status": "skipped" }

---

Phase 2: Research Error Handling Patterns

Use MCP tools to get up-to-date documentation.

For .NET:

MCP ref: "ASP.NET Core global exception handling middleware"
Context7: /dotnet/aspnetcore

For Python:

MCP ref: "FastAPI exception handlers custom exceptions"
Context7: /tiangolo/fastapi

Key Patterns to Research:

1. Middleware pipeline positioning
2. Exception type mapping to HTTP status codes
3. ProblemDetails (RFC 7807) format
4. Development vs Production error details
5. Logging integration

---

Phase 3: Decision Points

Q1: Error Response Format

Option	Description
ProblemDetails (RFC 7807) (Recommended)	Standardized format, widely adopted
Custom Format	Project-specific requirements

Q2: Error Detail Level

Environment	Stack Trace	Inner Exceptions	Request Details
Development	✓ Show	✓ Show	✓ Show
Production	✗ Hide	✗ Hide	✗ Hide

Q3: Error Taxonomy

Define standard error codes:

Code	HTTP Status	Description
VALIDATION_ERROR	400	Invalid input data
UNAUTHORIZED	401	Authentication required
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
CONFLICT	409	Resource state conflict
INTERNAL_ERROR	500	Unexpected server error

---

Phase 4: Generate Configuration

.NET Output Files

File	Purpose
Middleware/GlobalExceptionMiddleware.cs	Exception handling middleware
Exceptions/AppException.cs	Base exception class
Exceptions/ValidationException.cs	Validation errors
Exceptions/NotFoundException.cs	Not found errors
Models/ErrorResponse.cs	Error response model

Generation Process:

1. Use MCP ref to get current ASP.NET Core exception handling patterns
2. Generate GlobalExceptionMiddleware with:
   • Exception type to HTTP status mapping
   • Logging of exceptions
   • ProblemDetails response format
   • Environment-aware detail level
3. Generate custom exception classes

Registration Code:

app.UseMiddleware<GlobalExceptionMiddleware>();

Python Output Files

File	Purpose
exceptions/app_exceptions.py	Custom exception classes
exceptions/handlers.py	FastAPI exception handlers
models/error_response.py	Pydantic error models

Generation Process:

1. Use MCP ref to get current FastAPI exception handling patterns
2. Generate exception handlers with:
   • HTTPException handling
   • Custom AppException handling
   • Validation error handling
   • Request validation error handling
3. Generate custom exception classes

Registration Code:

app.add_exception_handler(AppException, app_exception_handler)
app.add_exception_handler(RequestValidationError, validation_exception_handler)

---

Phase 5: Validate

Validation Steps:

1. Syntax check:

   • .NET: dotnet build --no-restore
   • Python: python -m py_compile exceptions/handlers.py

2. Test error handling:

   • Create test endpoint that throws exception
   • Verify error response format
   • Check that stack trace hidden in Production

Expected Error Response (ProblemDetails):

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid input data",
  "instance": "/api/users",
  "errors": [
    { "field": "email", "message": "Invalid email format" }
  ],
  "traceId": "abc-123-def-456"
}

---

Return to Coordinator

{
  "status": "success",
  "files_created": [
    "Middleware/GlobalExceptionMiddleware.cs",
    "Exceptions/AppException.cs",
    "Models/ErrorResponse.cs"
  ],
  "packages_added": [],
  "registration_code": "app.UseMiddleware<GlobalExceptionMiddleware>();",
  "message": "Configured global exception handling"
}

---

Reference Links

• ASP.NET Core Error Handling
• FastAPI Handling Errors
• RFC 7807 Problem Details

---

Critical Rules

• Use ProblemDetails (RFC 7807) by default — standardized error response format
• Hide stack traces in Production — environment-aware detail level is mandatory
• Use MCP ref for current patterns — do not hardcode middleware from memory
• Idempotent — if GlobalExceptionMiddleware or exception_handlers.py exists, return status: "skipped"
• Map all custom exceptions to HTTP status codes — no unhandled exception types reaching the client

Definition of Done

• Context Store received (stack, framework, environment)
• Error handling patterns researched via MCP tools
• GlobalExceptionMiddleware generated (.NET) or exception handlers generated (Python)
• Custom exception classes created (AppException, ValidationException, NotFoundException)
• Error response model created (ProblemDetails format)
• Syntax validated (dotnet build or py_compile)
• Structured JSON response returned to ln-770 coordinator

---

Version: 2.0.0 Last Updated: 2026-01-10