...
Eroare Node.js · Asincron: callback-uri, promisiuni și timere

Warning: Detected unsettled top-level await at file:///app/index.js:9

Pe scurt

Un await de la nivelul de sus al unui modul ES așteaptă o promisiune care nu se mai rezolvă niciodată, iar Node se oprește cu codul de ieșire 13. De obicei lipsește apelul resolve() în new Promise sau evenimentul așteptat nu mai vine. Asigură-te că promisiunea se rezolvă sau se respinge pe orice drum.

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

Ce înseamnă

În modulele ES poți scrie await direct la nivelul de sus (top-level await). Node ține programul pornit cât timp are ceva de făcut: timere, cereri, fișiere deschise. Dacă toate s-au terminat, dar await-ul încă așteaptă o promisiune, nimic nu o mai poate rezolva vreodată. Atunci Node se oprește și afișează Detected unsettled top-level await, cu fișierul și linia acelui await, și ieșire cu codul 13.

Codul de după await nu rulează, deci programul pare că „se oprește la jumătate” fără o excepție clasică.

Cauze tipice: o funcție care întoarce new Promise(...) și nu apelează niciodată resolve (de exemplu în setTimeout ai pus altă funcție), o promisiune care așteaptă un eveniment care nu mai e emis, sau un once("close") pe ceva care nu se închide. Linia din mesaj îți arată await-ul blocat.

De ce apare: cauzele frecvente

1new Promise fără resolve

Greșit
JavaScript
function asteapta(ms) {
  return new Promise((resolve) => {
    setTimeout(() => {}, ms);
  });
}
await asteapta(100);
Corect
JavaScript
function asteapta(ms) {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}
await asteapta(100);

Promisiunea se rezolvă doar când apelezi resolve. Fără el, await așteaptă la nesfârșit, iar după ce timerul se termină Node nu mai are nimic de făcut.

2Eveniment care nu mai vine

Greșit
JavaScript
import { once } from "node:events";
const coada = new EventEmitter();
await once(coada, "gata"); // nimeni nu emite "gata"
Corect
JavaScript
import { once } from "node:events";
const coada = new EventEmitter();
setTimeout(() => coada.emit("gata"), 10);
await once(coada, "gata");

Cineva trebuie să emită evenimentul după ce ai început să-l aștepți; altfel așteptarea nu se termină.

3Folosește variantele gata făcute

Greșit
JavaScript
await new Promise((r) => setTimeout(() => console.log("gata"), 100));
Corect
JavaScript
import { setTimeout as asteapta } from "node:timers/promises";
await asteapta(100);
console.log("gata");

timers/promises îți dă un setTimeout care întoarce deja o promisiune rezolvată corect.

Repară tu

Repară eroarea, direct în pagină

Programul (modul ES) afișează etapele unei comenzi cu pauze între ele, dar funcția asteapta nu rezolvă niciodată promisiunea, așa că după prima etapă Node se oprește cu Warning: Detected unsettled top-level await și codul de ieșire 13. Repară asteapta, ca programul să afișeze toate cele trei etape.

Codul care dă eroarea
JavaScript
function asteapta(ms) {
  return new Promise((resolve) => {
    setTimeout(() => {}, ms);
  });
}

console.log("Comandă primită");
await asteapta(50);
console.log("Comandă pregătită");
await asteapta(50);
console.log("Comandă livrată");
După reparație, programul afișează
Comandă primită
Comandă pregătită
Comandă livrată
Indiciu

Funcția dată lui setTimeout trebuie să fie chiar resolve.

Alte forme ale mesajului

  • Warning: Detected unsettled top-level await at file:///app/index.mjs:3 await new Promise(() => {}); ^
  • Warning: Detected unsettled top-level await at file:///app/server.mjs:12

Cum o eviți pe viitor

  • În fiecare new Promise((resolve, reject) => ...), verifică că pe orice drum se apelează resolve sau reject.
  • Pentru pauze folosește setTimeout din node:timers/promises în loc să scrii propria promisiune.
  • Când aștepți un eveniment, pune și un timeout: await once(emitter, "x", { signal: AbortSignal.timeout(5000) }).
  • Dacă programul „se termină la jumătate” cu codul 13, uită-te la linia indicată de avertisment.

Întrebări frecvente

De ce nu primesc o eroare cu stivă de apeluri?

Pentru că nu a aruncat nimeni nicio eroare: promisiunea pur și simplu nu s-a terminat. Node observă doar că nu mai are nimic de făcut și se oprește cu codul 13.

În CommonJS se întâmplă la fel?

Acolo nu există top-level await. Dacă ai main().then(...) și promisiunea nu se rezolvă, programul se termină în tăcere cu codul 0, iar codul de după await nu rulează niciodată. E aceeași greșeală, doar mai greu de observat.

Erori înrudite

← Toate erorile Node.js

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ță Node.js de la zero, cu exerciții la fiecare lecție

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