{"record":{"id":"bc347594e4ad67ad","repo":"vitest-dev/vitest","slug":"environment-name-is-not-a-valid-environment","errorCode":null,"errorMessage":"Environment \"${name}\" is not a valid environment. Path \"${packageId}\" should export default object with a \"setup\" or/and \"setupVM\" method.","messagePattern":"Environment \"(.+?)\" is not a valid environment\\. Path \"(.+?)\" should export default object with a \"setup\" or/and \"setupVM\" method\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/integrations/env/loader.ts","lineNumber":74,"sourceCode":"\nasync function loadNativeEnvironment(\n  name: string,\n  root: string,\n  traces: Traces,\n): Promise<Environment> {\n  const packageId = name[0] === '.' || name[0] === '/'\n    ? pathToFileURL(resolve(root, name)).toString()\n    : import.meta.resolve(`vitest-environment-${name}`, pathToFileURL(root).toString())\n  const pkg = await traces.$(\n    'vitest.runtime.environment.import',\n    () => import(packageId) as Promise<{ default: Environment }>,\n  )\n  return resolveEnvironmentFromModule(name, packageId, pkg)\n}\n\nfunction resolveEnvironmentFromModule(name: string, packageId: string, pkg: { default: Environment }) {\n  if (!pkg || !pkg.default || typeof pkg.default !== 'object') {\n    throw new TypeError(\n      `Environment \"${name}\" is not a valid environment. `\n      + `Path \"${packageId}\" should export default object with a \"setup\" or/and \"setupVM\" method.`,\n    )\n  }\n  const environment = pkg.default\n  if (\n    environment.transformMode != null\n    && environment.transformMode !== 'web'\n    && environment.transformMode !== 'ssr'\n  ) {\n    throw new TypeError(\n      `Environment \"${name}\" is not a valid environment. `\n      + `Path \"${packageId}\" should export default object with a \"transformMode\" method equal to \"ssr\" or \"web\", received \"${environment.transformMode}\".`,\n    )\n  }\n  if (environment.transformMode) {\n    console.warn(`The Vitest environment ${environment.name} defines the \"transformMode\". This options was deprecated in Vitest 4 and will be removed in the next major version. Please, use \"viteEnvironment\" instead.`)\n    // keep for backwards compat","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/vitest/src/integrations/env/loader.ts#L56-L92","documentation":"When a custom environment name (not one of the built-ins like 'node', 'jsdom', 'happy-dom') is configured, Vitest resolves the package `vitest-environment-${name}` and imports its default export. resolveEnvironmentFromModule checks that the default export exists and is an object. If the package has no default export, or the default is not an object, this TypeError fires, telling you the expected shape (an object with setup/setupVM methods).","triggerScenarios":"Setting `environment: 'myenv'` in config where the package `vitest-environment-myenv` either doesn't exist, doesn't have a default export, or exports a non-object default (e.g. a function or string).","commonSituations":"Writing a custom Vitest environment but forgetting `export default`; naming mismatch between config and package; package misconfigured with named export instead of default; broken/partial environment package.","solutions":["Ensure your environment package has `export default { name, setup() { ... } }` (or setupVM).","Verify the package name matches `vitest-environment-${name}` and is installed/resolvable.","Check that the resolved module's default export is a plain object, not a function or class."],"exampleFix":"// before — environment package only has named export:\nexport function setup() { /* ... */ }\n\n// after — default export object:\nexport default { name: 'myenv', setup() { /* ... */ } }","handlingStrategy":"type-guard","validationCode":"// before publishing a custom environment, verify:\nconst env = (await import('vitest-environment-myenv')).default\nif (!(env && typeof env === 'object' && typeof env.setup === 'function')) {\n  throw new Error('environment package must default-export { name, setup } ')\n}","typeGuard":"function isValidEnvironment(v: unknown): v is { name: string; setup: Function } {\n  return typeof v === 'object' && v !== null\n    && typeof (v as any).setup === 'function'\n}","tryCatchPattern":null,"preventionTips":["Always export default an object with name and setup/setupVM from environment packages.","Name the package vitest-environment-${name} to match the config value."],"tags":["environment","config","custom-environment","module-export"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}