126 Java Exception Handling Agent Skill

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
• Review Java exception taxonomy and propagation

Workflow

• Compile project before exception-handling changes

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

• Read exception-handling reference

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

• Apply exception-handling improvements

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

• 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.