{"record":{"id":"7119a6d10bea9061","repo":"remix-run/react-router","slug":"error-loading-reactrouterconfigfile-error","errorCode":null,"errorMessage":"Error loading ${reactRouterConfigFile}: ${error}","messagePattern":"Error loading (.+?): (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/react-router-dev/config/config.ts","lineNumber":483,"sourceCode":"\n      if (configModule.default === undefined) {\n        return err(`${reactRouterConfigFile} must provide a default export`);\n      }\n\n      if (typeof configModule.default !== \"object\") {\n        return err(`${reactRouterConfigFile} must export a config`);\n      }\n\n      reactRouterUserConfig = configModule.default;\n\n      if (validateConfig) {\n        const error = validateConfig(reactRouterUserConfig);\n        if (error) {\n          return err(error);\n        }\n      }\n    } catch (error) {\n      return err(`Error loading ${reactRouterConfigFile}: ${error}`);\n    }\n  }\n\n  // Prevent mutations to the user config\n  reactRouterUserConfig = deepFreeze(cloneDeep(reactRouterUserConfig));\n\n  let presets: ReactRouterConfig[] = (\n    await Promise.all(\n      (reactRouterUserConfig.presets ?? []).map(async (preset) => {\n        if (!preset.name) {\n          throw new Error(\n            \"React Router presets must have a `name` property defined.\",\n          );\n        }\n\n        if (!preset.reactRouterConfig) {\n          return null;\n        }","sourceCodeStart":465,"sourceCodeEnd":501,"githubUrl":"https://github.com/remix-run/react-router/blob/6beaca39526d5716c3c112ebb0782765baa5a9ce/packages/react-router-dev/config/config.ts#L465-L501","documentation":"Any exception thrown while the Vite runner imports the React Router config file is wrapped in this message — the `${error}` suffix carries the underlying cause. Because the config file is loaded through Vite (supporting TS, imports of other modules, env usage), failures range from syntax errors to missing relative imports to exceptions in code the config executes at module scope.","triggerScenarios":"A syntax/parse error in `react-router.config.ts`; the config imports a module that fails to resolve (wrong relative path, missing dependency in node_modules); the config reads `process.env.SOME_VAR` and throws when it is undefined; a top-level await or side-effect that throws during import.","commonSituations":"Config imports a shared `./src/env.ts` whose path changed; using a package in the config that is a devDependency and missing in production/CI installs (`--production` install); accessing an env var that exists locally but not in CI; TS-only syntax errors after a toolchain upgrade.","solutions":["Read the tail of the message — it contains the real error (parse error with line/column, resolve error with the module name, or a runtime message).","Fix the referenced syntax error or import path in the config file.","If an env var access throws, default it (`process.env.X ?? fallback`) or add it to your environment/`.env` and CI secrets.","Ensure any package imported by the config is installed where the config is loaded (add to devDependencies for build-time)."],"exampleFix":"// before: react-router.config.ts\nimport { options } from \"./shared/options\"; // module missing / path typo\nexport default { ssr: options.ssr };\n\n// after\nexport default {\n  ssr: (process.env.SSR ?? \"true\") === \"true\",\n};","handlingStrategy":"try-catch","validationCode":"// smoke-import the config the same way the toolchain does, before CI build steps\nimport(\"./react-router.config.ts\")\n  .then(() => console.log(\"config loads\"))\n  .catch((e) => {\n    console.error(\"react-router.config.ts fails to load:\", e);\n    process.exit(1);\n  });","typeGuard":null,"tryCatchPattern":"try {\n  const config = await loadReactRouterConfig();\n} catch (e) {\n  // the wrapped message embeds the cause after ': '\n  const cause = String(e).split(\": \").slice(1).join(\": \");\n  console.error(\"Config load failed:\", cause);\n  process.exit(1);\n}","preventionTips":["Default all env reads in the config: process.env.X ?? fallback.","Keep the config file dependency-free or ensure its imports are installed in every environment that reads it (including CI).","Typecheck the config file in CI so syntax errors fail before the build step.","Use relative imports rooted at the config file's own directory."],"tags":["config","vite","module-resolution","environment"],"backgroundTag":"config-module-load-error","analyzedSha":"6beaca39526d5716c3c112ebb0782765baa5a9ce","analyzedAt":"2026-08-18T18:04:14.938Z","contentChangedAt":"2026-08-18T18:04:14.938Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}