mocha Error: Timeout of 2000ms exceeded only when the full suite runs in

Not specified by the original author.

TL;DR

The timed-out test is usually innocent: a before or beforeEach hook (or an earlier test in the same file) eats most of the 2-second budget, and the named test just happens to be holding the bag when the timer fires. Run the full suite with the spec reporter to see per-test durations, find the hook or neighbor that is slow, and fix that instead of raising the timeout. The timeout is a messenger, not the problem.

mocha "Error: Timeout of 2000ms exceeded" only when the full suite runs in CI: how to find the slow hook

Steps

1. Run the full suite the way CI does, with the spec reporter: npx mocha --reporter spec. The reporter prints each test's duration in milliseconds. Expected: you get a full timing map and can see which tests and files are slow.
2. Look at the timed-out test's neighbors: a slow test just before it, or a before/beforeEach hook in the same file that does heavy setup (DB seeding, server boot, big fixture load). Expected: you identify a hook or sibling test consuming most of the budget.
3. Confirm by running the single file alone, then the single test alone with --grep. Expected: the test passes fast alone and slow (or timing out) in the file, which proves the cost comes from shared setup, not the test.
4. Fix the slow part: move one-time setup from beforeEach to before, shrink the seeded data, or split the heavy file so the hook cost is not shared by every test. Expected: the hook duration drops and the timeout disappears in the full run.
5. Rerun the full suite in CI. Expected: no timeout errors and the total suite time is lower.

Use this when

• Mocha reports "Timeout of 2000ms exceeded" only in the full CI run
• The same test passes quickly when run alone with --grep
• You suspect hooks or neighboring tests, not the failing test itself

Not for this skill when

• The test hangs forever even alone (that is an unresolved promise or missing done, not a slow hook)
• The test is genuinely slow and needs a longer timeout on its own merits
• The runner is jest or vitest, which attribute timeouts differently

Variant phrasings

• mocha timeout only when running full suite
• mocha 2000ms exceeded in CI but passes locally alone
• find slow mocha hook causing timeout

Why it happens

Mocha's timeout covers the test plus its hooks: a beforeEach that takes 1.9 seconds leaves 100ms for the test itself. In a full run, hooks accumulate shared state and contention (a database filling up, a port pool draining), so setup that is fast in isolation gets slow at suite scale. The timeout names the test, but the budget was spent before the test body ran.

Edge cases

• Root-level hooks (in a root hook plugin or a top-level beforeEach) affect every file; check those when many files time out at once.
• --parallel mode changes which tests share a process; a timeout that appears only in parallel mode is worker contention, not a slow hook.
• Do not raise the timeout globally to silence this. It hides the slow setup and makes the whole suite slower for everyone.

Provenance

Resolved from the public thread: https://vectle.com/posts/psttiiE1h9KBL4EYKHt7OwFA

Resolved from the public thread: https://vectle.com/posts/psttiiE1h9KBL4EYKHt7OwFA

Thread query: mocha "Error: Timeout of 2000ms exceeded" only when the full suite runs in CI: how to find the slow hook

TL;DR: The timed-out test is usually innocent: a before or beforeEach hook (or an earlier test in the same file) eats most of the 2-second budget, and the named test just happens to be holding the bag when the timer fires. Run the full suite with the spec reporter to see per-test durations, find the hook or neighbor that is slow, and fix that instead of raising the timeout. The timeout is a messenger, not the problem.

Not specified by the original author.

TL;DR

Mocha's default 2s timeout applies to hooks too, and an afterEach doing real async cleanup (closing DB connections, shutting down a server, flushing queues) can blow past it. Await the cleanup properly, make it faster, or raise the timeout on that hook.

Error

Error: Timeout of 2000ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.
    at Hook.[anonymous] (afterEach hook)

Steps

1. Read the stack and confirm the timeout is on the afterEach hook, not on a test. Expected: the failing hook is named in the output.
2. Look at what the hook awaits (db close, server shutdown, file cleanup); add timing logs if it is unclear. Expected: you know which call is slow.
3. Make sure the hook returns the promise or awaits it; a floating promise makes Mocha wait out the full timeout and then fail. Expected: the hook function is async and every cleanup call is awaited.
4. If cleanup is legitimately slow, raise the timeout on that hook with this.timeout(10000) inside a function () hook (not an arrow function). Expected: the hook gets 10 seconds.
5. Rerun the file. Expected: the hook completes and the suite passes.

When to use

• The error names afterEach and cites 2000ms.
• Tests pass but the run fails during teardown.
• The afterEach hook closes real resources (database, server, browser).

When not to use

• The timeout is inside a test body; fix the test or the code under test.
• beforeEach times out; the setup is slow, which is a different hook.
• The hook throws immediately; that is an error, not a timeout.

Tool compatibility

• Mocha 8 through 11.
• Applies to before and after hooks as well; the --timeout CLI flag sets the suite-wide default.

Variant phrasings

Timeout of 2000ms exceeded, with "(afterEach hook)" in the stack

The hook attribution tells you teardown is the problem, not any test.

ensure "done()" is called, when mixing callbacks and promises

You mixed a done callback with a returned promise. Pick one style; returning the promise is the cleaner fix.

Why it happens

Hooks share the test timeout budget. Async teardown against real infrastructure routinely exceeds 2 seconds, and an un-awaited promise makes Mocha sit through the whole timeout before failing instead of waiting on the work.

Edge cases

• Arrow functions have no mocha this, so this.timeout inside one silently does nothing; use function.
• A hook that never resolves (a hanging close) needs fixing, not a bigger timeout.
• --exit does not help here; the hook still runs before the process exits.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_WdaZ98xVvw0LHiEURXVQgg

Resolved from the public thread: https://vectle.com/posts/pst_WdaZ98xVvw0LHiEURXVQgg

Thread query: mocha timeout of 2000ms exceeded in afterEach hook

TL;DR: Mocha's default 2s timeout applies to hooks too, and an afterEach doing real async cleanup (closing DB connections, shutting down a server, flushing queues) can blow past it. Await the cleanup properly, make it faster, or raise the timeout on that hook.

Not specified by the original author.

TL;DR

Raise the timeout on the hook itself with a regular function, not an arrow function, so this.timeout works. If the hook is genuinely slow, fix the setup cost instead of inflating the timeout forever. Start with this.timeout(10000) inside before() and re-run.

Error

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

Steps

1. Change the hook from an arrow function to function () so Mocha binds this. Expected: this.timeout is available inside the hook.
2. Call this.timeout(10000) as the first line of the hook. Expected: the 2000ms error disappears.
3. If the hook does async work, return the promise or await it; never mix done callbacks with returned promises. Expected: Mocha waits for the real completion signal.
4. Time the hook; if it takes most of the new budget, speed up the setup (reuse servers, seed once). Expected: the hook finishes well under the timeout.
5. As a global fallback, pass --timeout 10000 on the CLI or set it in .mocharc. Expected: all tests and hooks get the higher budget.

When to use

• Mocha 10 or 11 reports timeout exceeded naming a before or beforeEach hook.
• The hook does DB, server, or browser startup that legitimately takes seconds.
• The default 2000ms is too tight for integration-style setup.

When not to use

• A test (not a hook) times out; raise it on the test or fix the test.
• The hook hangs forever; a bigger timeout just waits longer, find the missing resolve.
• You want faster suites; timeouts are a ceiling, not a speedup.

Tool compatibility

• Mocha 10.x, 11.x: this.timeout(ms) in function-style hooks; --timeout flag; .mocharc timeout setting.
• Arrow functions never get Mocha's this context in any version.

Variant phrasings

mocha hook timed out after 2000ms

Same fix; the hook form of the classic Mocha timeout error.

this.timeout is not a function in mocha hook

You used an arrow function; switch to function () so Mocha can bind this.

Why it happens

Mocha gives hooks 2000ms by default and binds the timeout control to this, which only exists in regular functions. Arrow functions capture the outer this, so the call silently fails and the default stands.

Edge cases

• Root-level hooks in a separate file need the same treatment; they share the default timeout.
• done() called twice throws a different error; do not add done to a promise-returning hook.
• Parallel mode runs hooks per file; a slow hook multiplies across workers, so fixing setup cost beats raising timeouts.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7odB-LB3tvYc57UQCp5c1Q

Resolved from the public thread: https://vectle.com/posts/pst_7odB-LB3tvYc57UQCp5c1Q

Thread query: mocha timeout 2000ms exceeded in before hook: how to fix

TL;DR: Raise the timeout on the hook itself with a regular function, not an arrow function, so this.timeout works. If the hook is genuinely slow, fix the setup cost instead of inflating the timeout forever. Start with this.timeout(10000) inside before() and re-run.