stack/docs/scratchpads/281-fix-broad-exception-catching.md

Issue #281: Fix broad exception catching hiding system errors

Objective

Fix broad try-catch blocks in command.service.ts that catch ALL errors including system failures (OOM, DB failures, etc.), making debugging impossible.

Location

apps/api/src/federation/command.service.ts:168-194

Problem

The current implementation catches all errors in a broad try-catch block, which masks critical system errors as business logic failures. This makes debugging impossible and can hide serious issues like:

• Out of memory errors
• Database connection failures
• Network failures
• Module loading failures

Approach

1. Define specific error types for expected business logic errors
2. Only catch expected errors (e.g., module not found, command validation failures)
3. Let system errors (OOM, DB failures, network issues) propagate naturally
4. Add structured logging for business logic errors
5. Add comprehensive tests for both business and system error scenarios

Implementation Plan

• Create custom error classes for expected business errors
• Update handleIncomingCommand to only catch expected errors
• Add structured logging for security events
• Write tests for business logic errors (should be caught)
• Write tests for system errors (should propagate)
• Verify all tests pass
• Run quality gates (lint, typecheck, build)

Testing

• Test business logic errors are caught and handled gracefully ✅
• Test system errors propagate correctly ✅
• Test error logging includes appropriate context ✅
• Maintain 85%+ coverage ✅

Results

• Created CommandProcessingError hierarchy in apps/api/src/federation/errors/command.errors.ts
• System errors now propagate correctly (no longer caught)
• Business logic errors handled gracefully with error responses
• All 286 federation tests pass
• Lint, typecheck, build all pass
• Commit: f53f310

Notes

• This is a P0 security issue - proper error handling is critical for production debugging
• Follow patterns from other federation services
• Ensure backward compatibility with existing error handling flows
• COMPLETED ✅