123-java-exception-handling

Original：🇺🇸 English

Translated

Use when you need to apply Java exception handling best practices — including using specific exception types, managing resources with try-with-resources, securing exception messages, preserving error context via exception chaining, validating inputs early with fail-fast principles, handling thread interruption correctly, documenting exceptions with @throws, enforcing logging policy, translating exceptions at API boundaries, managing retries and idempotency, enforcing timeouts, attaching suppressed exceptions, and propagating failures in async/reactive code. This should trigger for requests such as Exception handling; Use try-with-resources in Java code; Create exception chaining in Java code; Apply fail-fast validation in Java code. Part of cursor-rules-java project

3installs

Sourcejabrena/cursor-rules-java

Added on2026-05-19

NPX Install

npx skill4agent add jabrena/cursor-rules-java 123-java-exception-handling

SKILL.md Content

View Translation Comparison →

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

Compile project before exception-handling changes

Run

./mvnw compile

or

mvn compile

and stop immediately if compilation fails.

Read exception-handling reference

Read

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