Maaz Zindani

Loading the index…

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

Mocha async test fails with a 2000ms timeout

ErrorError: Timeout of 2000ms exceeded

Short answer

Mocha gives every test and hook 2000 milliseconds by default. The error means the test did not finish in that time. Either the work is truly slower and needs a bigger timeout, or the test never signals it is done: done() is not called, the promise is not returned, or this.timeout sits in an arrow function.

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

Fix it fast

  1. 1Find out which cause you have

    Run the single failing test with timeouts switched off. If it then passes after a few seconds it is slow; if it hangs forever it never finishes.

    npx mocha test/my.test.js --timeout 0
  2. 2Match what you see, then jump to its fix

    1. 1With --timeout 0 the test passes, after more than 2 secondsThe work really takes longer than 2 secondsFix
    2. 2The test hangs with --timeout 0, or exits silently without a resultThe test never tells Mocha it is finishedFix
    3. 3You set this.timeout(10000) but the error still says 2000msthis.timeout() is inside an arrow functionFix

What does the error look like?

  • Error: Timeout of 2000ms exceeded

Cause 1 of 3

The work really takes longer than 2 seconds

1Check

Time the call the test waits for. A real network call, a database query or a cold start often goes over the default.

npx mocha test/my.test.js --timeout 10000

2Fix

Raise the limit only for the suite or test that needs it. Inside a normal function use this.timeout, or chain .timeout() on the test. Use the command line option to change it for the whole run.

describe('report', function () {
  this.timeout(10000);          // whole suite
  it('builds the report', async function () {
    // ...
  });
  it('exports a file', async () => {
    // ...
  }).timeout(15000);            // this test only
});

3Verify

Run the suite again without the --timeout 0 flag.

npx mocha

Confirmed by mochajs.org

Did this fix it?

Cause 2 of 3

The test never tells Mocha it is finished

1Check

A test that takes a done argument waits until done() is called. A test that returns nothing and ignores the promise returns before the work ends. Look for a callback path that skips done(), or a promise that is not returned or awaited.

grep -n "done" test/my.test.js

2Fix

Use one style per test. With async and await, await the call. With a callback, call done() on success and done(err) on failure. Never call done() and also return a promise.

it('loads the user', async () => {
  const user = await getUser(1);   // awaited, so Mocha waits
  expect(user.id).to.equal(1);
});

3Verify

Run the test normally. It should now pass or fail at once, not after 2 seconds.

npx mocha test/my.test.js

Confirmed by mochajs.org

Did this fix it?

Cause 3 of 3

this.timeout() is inside an arrow function

1Check

Arrow functions take this from the surrounding code, so they cannot reach the Mocha context and this.timeout does nothing there.

grep -n "this.timeout" -r test/

2Fix

Change that callback to a regular function, or chain .timeout() on the test, which also works with arrow functions.

it('slow call', () => {
  // ...
}).timeout(10000);

3Verify

The error message shows the new limit, or the test passes.

npx mocha test/my.test.js

Confirmed by mochajs.org

Did this fix it?

How do I stop it coming back?

  • Keep tests fast: stub network and database calls so 2 seconds is plenty.
  • Set a longer timeout only on the suites that need it, not in the global config.
  • Pick one completion style per test (async/await is the simplest) and do not mix it with done.

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.