vitest-dev/vitest · error · AggregateError

Cannot resolve user fixtures. See errors for more…

Error message

Cannot resolve user fixtures. See errors for more information.

What it means

An AggregateError wrapping two or more fixture-resolution errors collected during TestFixtures.resolve. Each inner error describes a specific problem (unknown dependency, self-dependency, scope violation). Vitest batches them so you see all fixture mistakes at once instead of fixing them one at a time. Inspect `error.errors` to read the individual causes.

Solutions

Read `err.errors` (AggregateError) to list each underlying FixtureDependencyError.
Fix each referenced fixture: register missing ones, remove self-references, correct scope ordering.
Re-run; resolution is idempotent and will re-scan after edits.

Example fix

// before
const fixtures = {
  a: ({ b }) => {},     // b unknown
  c: ({ c }) => {},     // self-dep, no parent
  d: test.fn(async ({ use }) => use(1), { scope: 'test' }),
  e: test.fn(async ({ d, use }) => use(d), { scope: 'worker' }), // worker depends on test
}

// after: fix each cause, then re-resolve

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await runWithFixtures(fn, options)
} catch (e) {
  if (e instanceof AggregateError) {
    for (const inner of e.errors) console.error(inner.message)
  } else throw e
}

Prevention

Keep fixture dependency graphs shallow and acyclic.
Run a small fixture-graph test in CI that instantiates all fixtures.
Use TypeScript types for fixture dependencies so missing names surface at compile time.

When it happens

Trigger: Declaring several fixtures whose dependencies are invalid simultaneously: e.g., a fixture depending on an unregistered name, another depending on itself, and a third with a scope mismatch. All are detected in the single resolution pass.

Common situations: Large fixture files where multiple typos or refactoring mistakes accumulate; mixing test/worker/file scopes incorrectly across several fixtures; deleting a fixture but leaving references in others.

Related errors

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/07ac75bf4b088621. Report an issue: GitHub.

Appendix: source

Thrown at packages/vitest/src/runtime/runner/fixture.ts:234

          continue
        }
        if (depName === fixture.name && !fixture.parent) {
          errors.push(new FixtureDependencyError(`The "${fixture.name}" fixture depends on itself, but does not have a base implementation.`))
          continue
        }

        if (TestFixtures._fixtureScopes.indexOf(fixture.scope) > TestFixtures._fixtureScopes.indexOf(dep.scope)) {
          errors.push(new FixtureDependencyError(`The ${fixture.scope} "${fixture.name}" fixture cannot depend on a ${dep.scope} fixture "${dep.name}".`))
          continue
        }
      }
    }

    if (errors.length === 1) {
      throw errors[0]
    }
    else if (errors.length > 1) {
      throw new AggregateError(errors, 'Cannot resolve user fixtures. See errors for more information.')
    }
    return registrations
  }
}

const cleanupFnArrayMap = new WeakMap<
  object,
  Array<() => void | Promise<void>>
>()

export async function callFixtureCleanup(context: object): Promise<void> {
  const cleanupFnArray = cleanupFnArrayMap.get(context) ?? []
  for (const cleanup of cleanupFnArray.reverse()) {
    await cleanup()
  }
  cleanupFnArrayMap.delete(context)
}

View on GitHub (pinned to 1fa9837ec2)