vitest-dev/vitest · error · AggregateError

Failed to initialize projects. There were errors during…

Error message

Failed to initialize projects. There were errors during projects setup. See below for more details.

What it means

Project entries are resolved concurrently (Promise.allSettled). If any resolution rejects, the settled results are partitioned into entries and errors; when errors is non-empty, Vitest wraps them in an AggregateError with this message so the user sees every setup failure at once rather than just the first.

Solutions

Read each error inside the AggregateError to find which project/config failed.
Open the named config file and fix the underlying syntax/import/option error.
Temporarily reduce to a single project to isolate the failing config.
Re-run after each fix; remaining errors will surface in the next AggregateError.

Defensive patterns

Strategy: try-catch

Validate before calling

// Optionally pre-validate each config loads before the full run.
import { loadConfigFromFile } from 'vite'
async function validateConfigs(files: string[]) {
  for (const f of files) {
  try { await loadConfigFromFile({ command: 'serve', mode: 'test' }, f) }
  catch (err) { throw new Error(`Config ${f} failed to load: ${(err as Error).message}`) }
  }
}

Try / catch

try {
  await resolveProjects(...)
} catch (err) {
  if (err instanceof AggregateError) {
  for (const e of err.errors) console.error('Project setup error:', e)
  // fix each, then re-run
  }
  throw err
}

Prevention

Typecheck/lint all vitest.config files in CI.
Load each config in isolation to surface individual errors early.
Keep config files small and dependency-light.

When it happens

Trigger: One or more project config files fail to load/resolve (syntax error, invalid config, missing dependency, throw during config evaluation), producing rejected promises collected into the AggregateError.

Common situations: A syntax/typing error in a vitest.config file, an import that fails (missing dep), a config that throws, or an invalid option - across one or more workspace projects.

Related errors

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

Appendix: source

Thrown at packages/vitest/src/node/projects/resolveProjects.ts:404

      { root: projectRoot, configFile },
      path,
    )))
  }

  const settled = await Promise.allSettled(promises)
  const errors: Error[] = []
  const entries: ResolvedProjectEntry[] = []
  for (const result of settled) {
    if (result.status === 'rejected') {
      errors.push(result.reason)
    }
    else {
      entries.push(result.value)
    }
  }

  if (errors.length) {
    throw new AggregateError(
      errors,
      'Failed to initialize projects. There were errors during projects setup. See below for more details.',
    )
  }

  return flattenContainerEntries(context, entries)
}

/**
 * Replace container entries (file-based configs that declare `projects`) with
 * the projects they declare, recursively. A container behaves like the root
 * config: it doesn't run tests and never gets a Vite server; its projects
 * extend it by default and their names are prefixed with the container's name.
 */
async function flattenContainerEntries(
  context: ProjectsResolutionContext,
  entries: ResolvedProjectEntry[],
): Promise<ResolvedProjectEntry[]> {

View on GitHub (pinned to 1fa9837ec2)