Mocha "Error: Timeout of 2000ms exceeded" in CI

By Daniel Zoghalchali·Latchkey

A Mocha test exceeded the default 2000 ms timeout. The async test either never called done(), never returned its promise, or genuinely took longer than the limit.

What this error means

A test fails with "Error: Timeout of 2000ms exceeded. For async tests and hooks, ensure done() is called; if returning a Promise, ensure it resolves." It often surfaces only in slower CI.

Mocha output

  1) GET /users
       returns 200:
     Error: Timeout of 2000ms exceeded. For async tests and hooks, ensure
     "done()" is called; if returning a Promise, ensure it resolves.

Common causes

done() never called or promise not returned

A test takes the done callback but never calls it (e.g. an error path skips it), or it does async work without returning the promise, so Mocha waits until the timeout.

Work slower than 2000 ms

A real HTTP or DB round-trip legitimately exceeds the default 2s, especially under CI load.

How to fix it

Return the promise (drop done)

Returning a promise - or using async/await - lets Mocha track completion without a callback you might forget.

users.test.js

it('returns 200', async () => {
  const res = await request(app).get('/users');
  expect(res.status).to.equal(200);
});

Raise the timeout where work is truly slow

Terminal

// per test
it('slow', async function () {
  this.timeout(10000);
  /* ... */
});
// or via CLI
mocha --timeout 10000

How to prevent it

Prefer async/await or returned promises over done.
Set a realistic --timeout for integration suites.
Avoid arrow functions when you need this.timeout().

Frequently asked questions

What causes ""Timeout of 2000ms exceeded""?

A test takes the done callback but never calls it (e.g. an error path skips it), or it does async work without returning the promise, so Mocha waits until the timeout.

How do I fix "Timeout of 2000ms exceeded"?