...
Eroare Java · Reflecție, module și alte API-uri

java.util.concurrent.TimeoutException

Pe scurt

Ai așteptat un rezultat cu limită de timp (future.get(timeout) sau orTimeout) și rezultatul n-a venit la timp. Mărește limita doar dacă operația chiar durează, altfel tratează cazul: completeOnTimeout(valoareImplicita, ...) sau prinde excepția.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

Future.get(timp, unitate) așteaptă rezultatul cel mult cât îi spui. Dacă timpul trece, aruncă TimeoutException (de obicei fără mesaj). Varianta cu orTimeout(...) pe un CompletableFuture termină future-ul cu aceeași excepție, iar la join() o vezi împachetată: CompletionException: java.util.concurrent.TimeoutException.

Cauze frecvente:

  • serviciul apelat (un API, o bază de date) răspunde mai greu decât limita;
  • future-ul nu e completat niciodată: ai creat new CompletableFuture<>() și ai uitat complete(...), sau codul care trebuia să-l completeze a aruncat o excepție înainte;
  • limita e prea mică pentru operație.

Timeout-ul e un caz normal în programele care comunică prin rețea. Nu-l ascunde: decide ce face aplicația atunci, de exemplu folosește o valoare implicită, încearcă din nou sau afișează un mesaj.

De ce apare: cauzele frecvente

1Future care nu e completat niciodată

Greșit
JAVA
CompletableFuture<String> raspuns = new CompletableFuture<>();
// ... nimeni nu cheamă raspuns.complete(...)
String r = raspuns.get(1, TimeUnit.SECONDS);
Corect
JAVA
CompletableFuture<String> raspuns = new CompletableFuture<>();
raspuns.complete("ok");
String r = raspuns.get(1, TimeUnit.SECONDS);

Un future e gata doar după complete(...) sau completeExceptionally(...). Fără ele, orice get cu limită expiră.

2Valoare implicită la timeout

Greșit
JAVA
double curs = cursValutar().get(200, TimeUnit.MILLISECONDS);
Corect
JAVA
double curs = cursValutar()
    .completeOnTimeout(4.97, 200, TimeUnit.MILLISECONDS)
    .join();

completeOnTimeout dă o valoare de rezervă când rezultatul întârzie, în loc să arunce excepție.

3Timeout prins și tratat

Greșit
JAVA
String r = viitor.orTimeout(2, TimeUnit.SECONDS).join();
Corect
JAVA
String r = viitor.orTimeout(2, TimeUnit.SECONDS)
    .exceptionally(e -> "serviciu indisponibil")
    .join();

exceptionally transformă timeout-ul (și alte erori) într-un rezultat pe care aplicația îl poate afișa.

Repară tu

Repară eroarea, direct în pagină

Programul așteaptă cursul valutar de la un serviciu care nu răspunde și se oprește cu java.util.concurrent.TimeoutException. Folosește completeOnTimeout cu valoarea implicită 4.97 și 100 de milisecunde, apoi join(), ca programul să afișeze Curs EUR: 4.97.

Codul care dă eroarea
JAVA
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

public class Main {
    static CompletableFuture<Double> cursDeLaServiciu() {
        // serviciul nu raspunde: nimeni nu completeaza rezultatul
        return new CompletableFuture<>();
    }

    public static void main(String[] args) throws Exception {
        double curs = cursDeLaServiciu().get(100, TimeUnit.MILLISECONDS);
        System.out.println("Curs EUR: " + curs);
    }
}
După reparație, programul afișează
Curs EUR: 4.97
Indiciu

curs.completeOnTimeout(4.97, 100, TimeUnit.MILLISECONDS).join()

Alte forme ale mesajului

  • java.util.concurrent.CompletionException: java.util.concurrent.TimeoutException
  • java.util.concurrent.ExecutionException: java.util.concurrent.TimeoutException
  • java.net.http.HttpTimeoutException: request timed out

Cum o eviți pe viitor

  • Pune limite de timp pe orice așteptare din rețea, dar alege-le după cât durează operația în mod normal.
  • Pentru fiecare timeout, decide comportamentul: valoare implicită (completeOnTimeout), reîncercare sau mesaj de eroare.
  • Când creezi manual un CompletableFuture, asigură-te că fiecare cale de cod îl completează, inclusiv cea cu excepție (completeExceptionally).
  • Scrie în log cât a durat operația, ca să vezi dacă limita e prea mică.

Întrebări frecvente

De ce TimeoutException nu are mesaj?

get o aruncă fără text. Contextul (ce operație și cât ai așteptat) trebuie adăugat de tine când o prinzi sau când scrii în log.

Se oprește operația când apare timeout-ul?

Nu neapărat. get(timeout) doar renunță să mai aștepte; operația poate continua în fundal. Dacă vrei s-o oprești, cheamă cancel(true), iar codul operației trebuie să reacționeze la întrerupere.

Erori înrudite

← Toate erorile Java

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață Java de la zero, cu exerciții la fiecare lecție

Curs Java: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.