Designing for Failure

Why this matters

• The difference between a five-minute fix and a five-hour investigation is almost always what was in the exception, and whether anything swallowed it.
• Custom exceptions let callers handle specific failures instead of parsing error strings, which is the difference between an API and a guess.
• final, finally and finalize sound alike, are unrelated, and get asked together constantly.

Custom exceptions

Define one when callers need to distinguish your failure from everything else. Give it the fields a caller or a log would need.

public class InsufficientFundsException extends RuntimeException {

    private final String accountId;
    private final BigDecimal requested;
    private final BigDecimal available;

    public InsufficientFundsException(String accountId, BigDecimal requested, BigDecimal available) {
        super("Account %s has %s but %s was requested"
                .formatted(accountId, available, requested));
        this.accountId = accountId;
        this.requested = requested;
        this.available = available;
    }

    public String accountId()     { return accountId; }
    public BigDecimal requested() { return requested; }
    public BigDecimal available() { return available; }

    public BigDecimal shortfall() {
        return requested.subtract(available);
    }
}

Anti-patterns to drop

The empty catch block

try {
    riskyOperation();
} catch (Exception e) {
    // nothing
}

The failure happened, and now nobody will ever know. This turns a clear error into mysterious wrong behaviour somewhere else entirely. If you genuinely expect and can ignore a specific exception, say so:

try {
    Files.delete(temporaryFile);
} catch (NoSuchFileException e) {
    // Already gone, which is the outcome we wanted.
}

A comment explaining why ignoring is correct is what separates this from the anti-pattern.

printStackTrace

catch (IOException e) {
    e.printStackTrace();      // goes to stderr, unstructured, no context, invisible in production
}

It writes to standard error outside your logging framework, so it carries no timestamp, no log level, no request identifier, and will not appear in your log aggregation. Use the logger and pass the exception as the last argument so the framework formats the trace:

catch (IOException e) {
    log.error("Failed to read config from {}", path, e);
}

Losing the cause

catch (SQLException e) {
    throw new DataAccessException("Query failed");      // the real reason is gone
}

Always pass it through. This is the most expensive single habit in exception handling.

Exceptions as control flow

// Wrong: an exception per iteration, each filling in a stack trace
try {
    while (true) {
        process(iterator.next());
    }
} catch (NoSuchElementException e) {
    // loop finished
}

Constructing an exception captures the stack, which is far more expensive than a comparison. Use the condition that exists for the purpose — while (iterator.hasNext()).

Catching what you cannot handle

catch (Exception e) {              // also catches every bug in the block
    return defaultValue;
}

A NullPointerException from your own mistake now silently returns a default. Catch the specific types you can genuinely act on, and let the rest reach a handler that reports them.

What to log, and once

// Wrong: logged at every layer, producing four traces for one failure
public Order load(String id) {
    try {
        return repository.find(id);
    } catch (SQLException e) {
        log.error("Database error", e);          // logged here
        throw new OrderException("Load failed", e);   // and again by the caller, and again above that
    }
}

// Right: wrap with context here, log once where it is handled
public Order load(String id) {
    try {
        return repository.find(id);
    } catch (SQLException e) {
        throw new OrderException("Could not load order " + id, e);
    }
}

InterruptedException is special

Swallowing this one breaks a mechanism the whole platform depends on.

// Wrong: the interruption request is discarded
try {
    Thread.sleep(1000);
} catch (InterruptedException e) {
    // ignored
}

// Right: either propagate it, or restore the flag so callers can see it
try {
    Thread.sleep(1000);
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();     // restore the interrupted status
    return;                                  // and stop what you were doing
}

Catching InterruptedException clears the thread's interrupted flag. If you neither rethrow nor restore it, code further up that checks for interruption will never see the request, and a thread pool shutdown will hang.

final, finally and finalize

Three unrelated things with similar names.

finalize() was unreliable by design — there was no guarantee it would ever run, it could resurrect objects, and it delayed collection. Use try-with-resources for deterministic cleanup. For native resources, java.lang.ref.Cleaner is the modern replacement.

A short checklist

Common misreadings

• "A custom exception should extend Exception to be proper." Extend RuntimeException unless callers have a real recovery path.
• "printStackTrace() is fine in development." It builds the habit, and it reaches production in the one class nobody reviewed.
• "Catching broadly is defensive." It is the opposite: it hides the bugs you most want to see.
• "Logging and rethrowing is thorough." It produces duplicate traces and makes incidents harder to read.
• "finalize() is a safety net." It was never guaranteed to run and no longer exists.
• "Swallowing InterruptedException is harmless." It discards a cancellation request and can hang a shutdown.