{"record":{"id":"4ac5cd05813f942d","repo":"vitejs/vite","slug":"local-cannot-be-used-as-a-mode-name-because-it-c","errorCode":null,"errorMessage":"\"local\" cannot be used as a mode name because it conflicts with the .local postfix for .env files.","messagePattern":"\"local\" cannot be used as a mode name because it conflicts with the \\.local postfix for \\.env files\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vite/src/node/env.ts","lineNumber":42,"sourceCode":"  }\n\n  return []\n}\n\n/**\n * Load `.env` files within the `envDir` and merge them with the matching\n * variables already present in `process.env`.\n */\nexport function loadEnv(\n  mode: string,\n  envDir: string | false,\n  prefixes: string | string[] = 'VITE_',\n): Record<string, string> {\n  const start = performance.now()\n  const getTime = () => `${(performance.now() - start).toFixed(2)}ms`\n\n  if (mode === 'local') {\n    throw new Error(\n      `\"local\" cannot be used as a mode name because it conflicts with ` +\n        `the .local postfix for .env files.`,\n    )\n  }\n  prefixes = arraify(prefixes)\n  const env: Record<string, string> = {}\n  const envFiles = getEnvFilesForMode(mode, envDir)\n\n  debug?.(`loading env files: %O`, envFiles)\n\n  const parsed = Object.fromEntries(\n    envFiles.flatMap((filePath) => {\n      const stat = tryStatSync(filePath)\n      // Support FIFOs (named pipes) for apps like 1Password\n      if (!stat || (!stat.isFile() && !stat.isFIFO())) return []\n\n      const parsedEnv = parseEnv(fs.readFileSync(filePath, 'utf-8'))\n      return Object.entries(parsedEnv as Record<string, string>)","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/vitejs/vite/blob/b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab/packages/vite/src/node/env.ts#L24-L60","documentation":"loadEnv reserves the mode name 'local' because Vite appends .local to env filenames for local overrides (e.g. .env.development.local). If 'local' were a mode, .env.local would collide with .env.<mode> resolution, so loadEnv rejects it up front.","triggerScenarios":"Calling loadEnv('local', envDir) or starting Vite with --mode local. The check fires before any env file is read.","commonSituations":"CI or staging scripts that pass --mode local thinking it triggers local-only behavior; programmatic callers looping over a list of modes that includes 'local'.","solutions":["Pick a different mode name (e.g. development-local, staging) that does not collide with the .local suffix.","Use .env.<mode>.local files for local overrides instead of a 'local' mode.","If you only need a local override, leave mode as development and create .env.local."],"exampleFix":"// before\nvite build --mode local\n// after\nvite build --mode dev-local","handlingStrategy":"validation","validationCode":"function validateMode(mode) {\n  if (mode === 'local') return 'Mode \"local\" is reserved';\n  return null;\n}","typeGuard":"function isAllowedMode(mode) { return mode && mode !== 'local'; }","tryCatchPattern":null,"preventionTips":["Never use --mode local; rely on .env.<mode>.local files for overrides.","Validate programmatic mode values against a reserved-words list."],"tags":["env","mode","config"],"backgroundTag":null,"analyzedSha":"b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab","analyzedAt":"2026-08-11T11:49:19.515Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}