126-java-exception-handling

Java Exception Handling Guidelines

Identify and apply robust Java exception handling practices to improve error clarity, security, debuggability, and system reliability.

What is covered in this Skill?

• 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
• Failure propagation in async CompletionStage code

Scope: The reference is organized by examples (good/bad code patterns) for each core area. Apply recommendations based on applicable examples.

Constraints

Before applying any exception handling changes, ensure the project compiles. If compilation fails, stop immediately — do not proceed until resolved. After applying improvements, run full verification.

• MANDATORY: Run ./mvnw compile or mvn compile before applying any changes
• SAFETY: If compilation fails, stop immediately — do not proceed until the project is in a valid state
• VERIFY: Run ./mvnw clean verify or mvn clean verify after applying improvements
• BEFORE APPLYING: Read the reference for detailed good/bad examples, constraints, and safeguards for each exception handling pattern

When to use this skill

• Exception handling
• Use try-with-resources in Java code
• Create exception chaining in Java code
• Apply fail-fast validation in Java code

Workflow

1. Compile project before exception-handling changes

Run ./mvnw compile or mvn compile and stop immediately if compilation fails.

1. Read exception-handling reference

Read references/126-java-exception-handling.md and identify applicable failure-handling and observability improvements.

1. Apply exception-handling improvements

Refactor to specific exceptions, safe resource handling, error translation, and consistent logging patterns.

1. Verify with full build

Run ./mvnw clean verify or mvn clean verify after applying improvements.

Reference

For detailed guidance, examples, and constraints, see [references/126-java-exception-handling.md](references/126-java-exception-handling.md).