Java Exception Handling Guidelines

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

Prerequisites: Run ./mvnw compile or mvn compile before applying any changes. If compilation fails, stop immediately — do not proceed until the project is in a valid state.

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.

Scope: The reference is organized by examples (with good/bad code patterns) for each core area. Apply recommendations based on applicable examples; validate compilation before changes and run ./mvnw clean verify or mvn clean verify after applying improvements.

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/123-java-exception-handling.md.