jestjs/jest · error · Error

Cannot find `global.gc` function. Please run node with…

Error message

Cannot find `global.gc` function. Please run node with `--expose-gc` and report this issue in jest repo.

What it means

Thrown by runGC in collectHandles when, after attempting to enable garbage collection via v8.setFlagsFromString('--expose-gc') and evaluating gc in a new context, the gc function is still undefined. collectHandles uses GC to release weakly-held async resources so it can report which handles keep a test process alive; without GC the open-handles diagnostic cannot run.

Solutions

1. Run node with --expose-gc so global.gc is available from the start (Jest's CLI already does this, but programmatic launches may not)
2. Disable open-handle collection if not needed (it is best-effort)
3. Report the environment details to the Jest repo as the message requests, since standard Node builds should not hit this

Example fix

// before
node ./run-jest.js

// after
node --expose-gc ./run-jest.js

function assertGcAvailable(): void {
  if (typeof (globalThis as any).gc !== 'function') {
    throw new Error('global.gc is not available. Restart with node --expose-gc');
  }
}

function hasGc(): boolean {
  return typeof (globalThis as { gc?: unknown }).gc === 'function';
}

When it happens

Trigger: Running Jest (specifically the open-handles collection feature) on a Node build or runtime where --expose-gc is ineffective and global.gc is unavailable. This is rare on standard Node builds but can occur on restricted/embedded runtimes.

Common situations: Embedded Node distributions that strip v8 flags; sandboxed environments that block setFlagsFromString; unusual Node forks. The message asks users to launch node with --expose-gc and to report the issue upstream.

Related errors

• Changed files must be set when running with -o.
• Filter did not return a valid test list
• file must export a function at

AI-assisted analysis of jestjs/jest@8e6d128e4a (2026-08-10). Data as JSON: /api/errors/079b685a6ef10032. Report an issue: GitHub.

Appendix: source

Thrown at packages/jest-core/src/collectHandles.ts:53

  }

  return false;
}

const alwaysActive = () => true;

const hasWeakRef = typeof WeakRef === 'function';

const asyncSleep = promisify(setTimeout);

let gcFunc: (() => void) | undefined = (globalThis as any).gc;
function runGC() {
  if (!gcFunc) {
    v8.setFlagsFromString('--expose-gc');
    gcFunc = vm.runInNewContext('gc');
    v8.setFlagsFromString('--no-expose-gc');
    if (!gcFunc) {
      throw new Error(
        'Cannot find `global.gc` function. Please run node with `--expose-gc` and report this issue in jest repo.',
      );
    }
  }

  gcFunc();
}

// Inspired by https://github.com/mafintosh/why-is-node-running/blob/master/index.js
// Extracted as we want to format the result ourselves
export default function collectHandles(): HandleCollectionResult {
  const activeHandles = new Map<
    number,
    {error: Error; isActive: () => boolean}
  >();
  const hook = asyncHooks.createHook({
    destroy(asyncId) {
      activeHandles.delete(asyncId);

View on GitHub (pinned to 8e6d128e4a)