123-java-exception-handling
npx machina-cli add skill jabrena/cursor-rules-java/123-java-exception-handling --openclawJava Exception Handling Guidelines
Identify and apply robust Java exception handling practices to improve error clarity, security, debuggability, and system reliability.
Core areas: Specific exception types instead of generic Exception/RuntimeException, try-with-resources for automatic resource cleanup, secure exception messages that avoid information leakage, exception chaining to preserve full error context, early input validation with IllegalArgumentException/NullPointerException, InterruptedException handling with interrupted-status restoration, @throws JavaDoc documentation, fail-fast principle, structured logging with correlation IDs avoiding log-and-throw duplication, API boundary translation via centralized exception mappers, bounded retry with backoff for idempotent operations only, timeout enforcement with deadline propagation, Throwable#addSuppressed for secondary cleanup failures, never catching Throwable/Error, observability via error metrics, and failure propagation in async CompletionStage code.
Prerequisites: Run ./mvnw compile before applying any changes. If compilation fails, stop immediately — do not proceed until the project is in a valid state.
Multi-step scope: Step 1 validates the project compiles. Step 2 categorizes exception handling issues by severity (CRITICAL, MAINTAINABILITY, SECURITY, OBSERVABILITY) and area (validation, resource management, logging, boundary translation, async propagation). Step 3 replaces generic exception catches with specific types and introduces custom exceptions where needed. Step 4 wraps resource-managing code with try-with-resources. Step 5 audits exception messages for sensitive data exposure and sanitizes them. Step 6 adds exception chaining (initCause/constructor) to preserve original context. Step 7 adds early null/argument validation at method entry points. Step 8 fixes InterruptedException handling to restore interrupted status. Step 9 aligns logging to log-once-at-boundary policy with correlation IDs. Step 10 adds centralized exception mappers at API boundaries (controllers, message handlers). Step 11 applies bounded retry with backoff only to idempotent operations. Step 12 enforces timeouts and propagates deadline-exceeded errors. Step 13 uses addSuppressed when rethrowing after cleanup failures. Step 14 removes any catches of Throwable or Error. Step 15 emits error-class metrics and ensures observability for SLO/SLA monitoring. Step 16 runs ./mvnw clean verify to confirm all tests pass after changes.
Before applying changes: Read the reference for detailed good/bad examples, constraints, and safeguards for each exception handling pattern.
Reference
For detailed guidance, examples, and constraints, see references/127-java-exception-handling.md.
Source
git clone https://github.com/jabrena/cursor-rules-java/blob/main/skills/123-java-exception-handling/SKILL.mdView on GitHub Overview
This skill encapsulates robust Java exception handling guidelines to improve error clarity, security, debuggability, and reliability. It covers using specific exception types, try-with-resources, secure messages, exception chaining, fail-fast input validation, proper InterruptedException handling, @throws documentation, boundary translation, bounded retry with backoff, timeouts, suppressed exceptions, and async propagation.
How This Skill Works
The skill compiles a structured workflow: identify hotspots, replace broad catches with specific exceptions, wrap resources with try-with-resources, sanitize messages, preserve context via chaining, validate inputs early, handle interruptions correctly, document throws, enforce logging and boundaries, and ensure observability. It emphasizes API boundary translation, proper retry/backoff, timeouts, addSuppressed usage, and avoiding Throwable/Error catches, including in async/reactive code.
When to Use It
- Designing Java APIs or libraries that require precise error semantics and clear failure modes
- Implementing resource management where automatic cleanup is critical (files, streams, DB cursors)
- Building idempotent operations with bounded retry and backoff across services
- Propagating errors across API boundaries and within async/reactive code paths
- Auditing and sanitizing error messages while enforcing secure, observable logging
Quick Start
- Step 1: ./mvnw compile to verify the project is in a valid state
- Step 2: Replace generic catches with specific exceptions; introduce custom ones where needed
- Step 3: Wrap resource-managing code with try-with-resources and implement API boundary translation and proper logging
Best Practices
- Prefer specific exception types; avoid catch-all except blocks for Exception/Throwable
- Use try-with-resources for automatic resource cleanup and to prevent leaks
- Sanitize exception messages to avoid leaking sensitive data; preserve context with chaining
- Validate inputs early (fail-fast) by throwing IllegalArgumentException or NullPointerException
- Handle InterruptedException by restoring the interrupted status and propagating appropriately
Example Use Cases
- A DAO layer converts SQLException into a DataAccessException while preserving the original cause for diagnostics
- An API boundary uses a centralized exception mapper to translate domain exceptions into ApiException with HTTP status codes
- A service method validates null or invalid arguments at entry and throws NullPointerException/IllegalArgumentException
- A long-running task catches InterruptedException, re-interrupts the thread, and throws a CancellationException to surface cancellation
- A try-with-resources block ensures a secondary cleanup failure is attached via addSuppressed to the primary exception
