Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js refuses to run a file because of await

ErrorThe error points at an await inside a callback, or at an await at the top of a file

Short answer

Node.js only allows await inside an async function, or at the top level of an ES module. The error means your await sits in a plain callback, or in a file Node.js loads as CommonJS. Mark the enclosing function async, or turn the file into a module with .mjs or a package.json type field.

  • Applies to Node.js 22, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the file and read the line number and the caret under the await. Then look at the function that directly contains that line: is it marked async, or is the line at the very top of the file?

    node index.js
  2. 2Match what you see, then jump to its fix

    1. 1The error points at an await inside arr.forEach(...), .on('event', ...), .then(...) or another inner function, even though the outer function is asyncThe await is inside a callback that is not asyncFix
    2. 2The await is at the very top of the file (not inside any function), and the file uses require() or sits in a package whose package.json says commonjsTop-level await in a file that Node.js loads as CommonJSFix

What does the error look like?

  • The error points at an await inside a callback, or at an await at the top of a file
  • SyntaxError: await is only valid in async functions, async generators and modules

Cause 1 of 2

The await is inside a callback that is not async

1Check

async applies to one function only. An inner arrow function or callback is a separate function and needs its own async keyword.

// fails: the inner callback is not async
items.forEach((item) => {
  const row = await load(item);
});

2Fix

Add async to the function that contains the await. If you wanted the items handled one after another, use a for...of loop inside the async function instead of forEach.

async function run(items) {
  for (const item of items) {
    const row = await load(item);
    console.log(row);
  }
}

3Verify

Run the file again. The syntax error is gone and the loop runs in order.

node index.js

Confirmed by developer.mozilla.org

Did this fix it?

Cause 2 of 2

Top-level await in a file that Node.js loads as CommonJS

1Check

Node.js treats a .js file as CommonJS when the nearest package.json has no type field or says commonjs, and always for .cjs. Top-level await is allowed only in an ES module.

grep '"type"' package.json
ls *.cjs *.mjs 2>/dev/null

2Fix

Either make the file an ES module (rename it to .mjs, or set the type field to module in package.json and switch require to import), or keep CommonJS and wrap the awaited work in an async function that you call.

// option A, package.json
{ "type": "module" }

// option B, stay in CommonJS
async function main() {
  const data = await load();
  console.log(data);
}
main().catch(console.error);

3Verify

Run the file. If you switched to modules, every require() in it must now be an import, or Node.js will tell you.

node index.mjs

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Give every function that contains await the async keyword when you write it, including small callbacks.
  • Set the type field in package.json on purpose, so the module system of every .js file is never a guess.
  • Run your linter with an async-aware rule set so a stray await is flagged in the editor before you run the file.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.