Home › Java exceptions › TimeoutException

What it looks like

java.util.concurrent.TimeoutException

Extends Exception in java.util.concurrent.

What it means

Methods that take a timeout (Future.get(10, SECONDS), CompletableFuture.orTimeout, ExecutorService.invokeAll with a limit, CountDownLatch.await) throw or report TimeoutException when the time elapses. The task itself is not stopped: the future keeps running unless you cancel it, so timing out is a decision about waiting, not about the work.

Common causes

• The task is slower than the limit: a slow database query or remote call.
• Thread pool starvation: the task is queued behind others and has not started.
• A deadlock or a blocked thread that never completes the future.
• A timeout shorter than the realistic latency of the dependency.

How to fix it

1. Cancel the future on timeout with future.cancel(true) so resources are released.
2. Check pool size and queue length; a full pool shows up as timeouts.
3. Set the timeout from measured latency, with a margin, and keep client and server timeouts consistent.
4. Return a fallback or an error response for the caller instead of letting the exception escape.

Broken and fixed

String result = future.get(1, TimeUnit.SECONDS); // task keeps running afterwards

try {
    return future.get(1, TimeUnit.SECONDS);
} catch (TimeoutException e) {
    future.cancel(true);
    return fallback();
}

🔎 Unravel the failing code 🔎 Unravel the fix

Debug it faster

Paste the whole stack trace into the stack trace beautifier to hide framework frames, jump to the root cause and find the first line of your own code. It runs in your browser, so the trace never leaves your machine.

Related exceptions