{"id":"bf3c549f03a8f2ba","repo":"vitest-dev/vitest","slug":"environment-name-is-not-a-valid-environment-bf3c54","errorCode":null,"errorMessage":"Environment \"${name}\" is not a valid environment. Path \"${packageId}\" should export default object with a \"transformMode\" method equal to \"ssr\" or \"web\", received \"${environment.transformMode}\".","messagePattern":"Environment \"(.+?)\" is not a valid environment\\. Path \"(.+?)\" should export default object with a \"transformMode\" method equal to \"ssr\" or \"web\", received \"(.+?)\"\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/integrations/env/loader.ts","lineNumber":85,"sourceCode":"    () => 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\n    environment.viteEnvironment ??= environment.transformMode === 'ssr'\n      ? 'ssr'\n      : 'client'\n  }\n  return environment\n}\n\nexport async function loadEnvironment(\n  name: string,\n  root: string,\n  rpc: WorkerRPC,","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/integrations/env/loader.ts#L67-L103","documentation":"A custom environment may optionally declare `transformMode` to control module transform, but it must be exactly `'ssr'` or `'web'`. Any other string value is rejected at load time to prevent ambiguous transform behavior. (Note: `transformMode` is deprecated in favor of `viteEnvironment` and emits a warning when present.)","triggerScenarios":"A custom environment whose default export sets `transformMode` to a value other than `'ssr'` or `'web'` — e.g. `'node'`, `'browser'`, `'client'`, `null`, a number, or a typo.","commonSituations":"Porting a config from another framework that uses different transform-mode vocabulary (e.g. `'browser'`), typos, or assuming `'client'` is valid (the legacy mapping converts `'web'`→`'client'` internally but the input must be `'web'`).","solutions":["Set `transformMode` to either `'ssr'` or `'web'` (or omit it entirely).","Prefer the non-deprecated `viteEnvironment: 'ssr' | 'client'` over `transformMode`.","If you wrote `'client'`, change it to `'web'`; if you wrote `'node'`, change it to `'ssr'`."],"exampleFix":"// before\nexport default { name: 'myenv', transformMode: 'browser', setup() {} }\n// after\nexport default { name: 'myenv', viteEnvironment: 'client', setup() {} }","handlingStrategy":"validation","validationCode":"const mode = env.default.transformMode\nif (mode != null && mode !== 'ssr' && mode !== 'web') {\n  throw new Error(`invalid transformMode: ${mode}`)\n}","typeGuard":"function isValidTransformMode(v: unknown): v is 'ssr' | 'web' | undefined {\n  return v == null || v === 'ssr' || v === 'web'\n}","tryCatchPattern":null,"preventionTips":["Prefer the non-deprecated `viteEnvironment: 'ssr' | 'client'` over `transformMode`.","Restrict `transformMode` to exactly `'ssr'` or `'web'` or omit it."],"tags":["environment","config","custom-environment","validation"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}