ForgeLM/.agents/rules/error-handling-principles.md

trigger, description

trigger	description
model_decision	When implementing error handling, working with error types, or designing error recovery strategies (validation errors, business rule violations, infrastructure failures, resource cleanup)

Error Handling Principles

1. Never Fail Silently:

• All errors must be handled explicitly (no empty catch blocks)
• If you catch an error, do something with it (log, return, transform, retry)

2. Fail Fast:

• Detect and report errors as early as possible
• Validate at system boundaries before processing
• Don't process invalid data hoping it'll work out

3. Provide Context:

• Include error codes, correlation IDs, actionable messages
• Enough information for debugging without exposing sensitive details
• Example: "Database query failed (correlation-id: abc-123)" not "SELECT * FROM users WHERE..."

4. Separate Concerns:

• Different handlers for different error types
• Business errors ≠ technical errors ≠ security errors

5. Resource Cleanup:

• Always clean up in error scenarios (close files, release connections, unlock resources)
• Use language-appropriate patterns (defer, finally, RAII, context managers)

6. No Information Leakage:

• Sanitize error messages for external consumption
• Don't expose stack traces, SQL queries, file paths, internal structure to users
• Log full details internally, show generic message externally

Application Error Object (Internal/Log Format)

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "User-friendly error message",
  "correlationId": "uuid-for-tracking",
  "details": {
    "field": "email",
    "issue": "Invalid email format",
    "provided": "invalid-email",
    "expected": "valid email format ([email protected])"
  }
}

Error Handling Checklist

• Are all error paths explicitly handled (no empty catch blocks)?
• Do errors include correlation IDs for debugging?
• Are sensitive details sanitized before returning to client?
• Are resources cleaned up in all error scenarios?
• Are errors logged at appropriate levels (warn for 4xx, error for 5xx)?
• Are error tests written (negative test cases)?
• Is error handling consistent across application?

Related Principles

• API Design Principles @api-design-principles.md - API Error Response Format section
• Logging and Observability Mandate @logging-and-observability-mandate.md
• Security Mandate @security-mandate.md
• Security Principles @security-principles.md
• Testing Strategy @testing-strategy.md
• Concurrency and Threading Mandate @concurrency-and-threading-mandate.md