home / skills / levnikolaevich / claude-code-skills / ln-772-error-handler-setup

ln-772-error-handler-setup skill

safe

/ln-772-error-handler-setup

This skill configures robust global error handling across .NET and Python backends, standardizing responses and safeguarding production detail exposure.

npx playbooks add skill levnikolaevich/claude-code-skills --skill ln-772-error-handler-setup

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

6.2 KB

---
name: ln-772-error-handler-setup
description: Configures global exception handling middleware
---

# 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:**
```csharp
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:**
```python
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):**
```json
{
  "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

```json
{
  "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](https://learn.microsoft.com/aspnet/core/web-api/handle-errors)
- [FastAPI Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/)
- [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807)

---

## 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

Overview

This skill configures global exception handling middleware for .NET (ASP.NET Core) and Python (FastAPI) backend projects. It produces environment-aware middleware/handlers, custom exception types, and a ProblemDetails-compliant error response model. The setup is idempotent and includes validation steps to ensure syntax and runtime behavior.

How this skill works

The skill accepts a context store with STACK, FRAMEWORK, PROJECT_ROOT, and ENVIRONMENT, then checks for existing handlers to skip if present. For .NET it generates a GlobalExceptionMiddleware, custom exception classes, and an ErrorResponse/ProblemDetails model; for Python it generates AppException classes, FastAPI handlers, and Pydantic error models. It registers handlers in the application pipeline and verifies behavior with build/compile checks and test endpoints.

When to use it

Bootstrapping a new backend project that needs standardized error handling
Adding centralized error concerns to an existing service without scattering try/catch
Enforcing RFC 7807 ProblemDetails responses across APIs
Ensuring production hides sensitive diagnostics while development shows full details
Implementing consistent mapping of domain errors to HTTP status codes

Best practices

Use ProblemDetails (RFC 7807) by default for API responses to standardize clients
Map custom exceptions to clear HTTP status codes and machine-readable error codes
Log full exception data server-side while omitting traces from production responses
Place global middleware early in the pipeline to capture unhandled exceptions
Make generation idempotent—detect existing middleware/handlers and skip

Example use cases

Generate GlobalExceptionMiddleware.cs, AppException.cs, and ErrorResponse.cs for an ASP.NET Core API
Create app_exceptions.py, handlers.py, and models/error_response.py for a FastAPI service
Add registration code like app.UseMiddleware<GlobalExceptionMiddleware>() or app.add_exception_handler(AppException, app_exception_handler)
Run dotnet build or python -m py_compile to validate syntax before integrating
Create a test endpoint that throws ValidationException to verify ProblemDetails output

FAQ

What error format does this setup use by default?

ProblemDetails (RFC 7807) is used by default for standardized, machine-readable error responses.

How does it handle environment-specific detail levels?

In Development it includes stack traces and request details; in Production it hides traces and sensitive information.