{"id":"03d91e6c30c67044","repo":"vitejs/vite","slug":"ssrloadmodule-requires-the-ssr-environment-to-be","errorCode":null,"errorMessage":"ssrLoadModule requires the 'ssr' environment to be a runnable environment.","messagePattern":"ssrLoadModule requires the 'ssr' environment to be a runnable environment\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vite/src/node/ssr/ssrModuleLoader.ts","lineNumber":26,"sourceCode":"import type { ViteDevServer } from '../server'\nimport { unwrapId } from '../../shared/utils'\nimport type { DevEnvironment } from '../server/environment'\nimport type { NormalizedServerHotChannel } from '../server/hmr'\nimport { buildErrorMessage } from '../server/middlewares/error'\nimport { isRunnableDevEnvironment } from '../../node'\nimport { ssrFixStacktrace } from './ssrStacktrace'\nimport { createServerModuleRunnerTransport } from './runtime/serverModuleRunner'\n\ntype SSRModule = Record<string, any>\n\nexport async function ssrLoadModule(\n  url: string,\n  server: ViteDevServer,\n  fixStacktrace?: boolean,\n): Promise<SSRModule> {\n  const environment = server.environments.ssr\n  if (!isRunnableDevEnvironment(environment)) {\n    throw new Error(\n      `ssrLoadModule requires the 'ssr' environment to be a runnable environment.`,\n    )\n  }\n  server._ssrCompatModuleRunner ||= new SSRCompatModuleRunner(environment)\n  url = unwrapId(url)\n\n  return instantiateModule(\n    url,\n    server._ssrCompatModuleRunner,\n    environment,\n    fixStacktrace,\n  )\n}\n\nasync function instantiateModule(\n  url: string,\n  runner: ModuleRunner,\n  environment: DevEnvironment,","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/vitejs/vite/blob/89620f09afcfef6b35e7bb8660132ab5b4d0cd3b/packages/vite/src/node/ssr/ssrModuleLoader.ts#L8-L44","documentation":"ssrLoadModule is a legacy compatibility API that evaluates SSR modules using a ModuleRunner, which requires the 'ssr' environment to be a RunnableDevEnvironment (one that owns and can drive a module runner). If the SSR environment is a plain DevEnvironment — the default in newer Vite versions where environments are not automatically runnable — the call throws. The isRunnableDevEnvironment type guard checks instanceof RunnableDevEnvironment before proceeding.","triggerScenarios":"Calling server.ssrLoadModule() on a server whose environments.ssr is a base DevEnvironment rather than a RunnableDevEnvironment. This is the default when the environment was not created with a runner factory. Using the legacy ssrLoadModule API on a server configured with custom environments that do not provide a runnable runner.","commonSituations":"Migrating to Vite's environment API (6.0+) where the default SSR environment is no longer runnable, but legacy code still calls ssrLoadModule. Framework integrations that create custom named environments. Downgrading/renaming environments so the 'ssr' key points to a non-runnable instance.","solutions":["Use the module-runner API directly (create a ModuleRunner or use environment.runner if available) instead of ssrLoadModule.","Ensure the SSR environment is created as a RunnableDevEnvironment by providing a runner factory in the environment config.","If you rely on ssrLoadModule, confirm server.environments.ssr instanceof RunnableDevEnvironment before calling."],"exampleFix":"// before\nconst mod = await server.ssrLoadModule('/src/entry-server.ts')\n\n// after — check runnability, then use the runner\nimport { isRunnableDevEnvironment } from 'vite'\nconst ssrEnv = server.environments.ssr\nif (isRunnableDevEnvironment(ssrEnv)) {\n  const mod = await ssrEnv.runner.import('/src/entry-server.ts')\n} else {\n  throw new Error('SSR environment is not runnable; configure a runner factory')\n}","handlingStrategy":"type-guard","validationCode":"import { isRunnableDevEnvironment } from 'vite'\n\nconst ssrEnv = server.environments.ssr\nif (!isRunnableDevEnvironment(ssrEnv)) {\n  throw new Error('Configure the ssr environment with a runner factory to use ssrLoadModule')\n}\nconst mod = await server.ssrLoadModule(url)","typeGuard":"import { isRunnableDevEnvironment } from 'vite'\nimport type { RunnableDevEnvironment } from 'vite'\n\nfunction assertRunnable(env): asserts env is RunnableDevEnvironment {\n  if (!isRunnableDevEnvironment(env)) {\n    throw new Error(`Environment '${env.name}' is not runnable`)\n  }\n}","tryCatchPattern":null,"preventionTips":["Prefer the module-runner API (environment.runner.import) over the legacy ssrLoadModule.","When creating environments programmatically, pass a runner factory to get a RunnableDevEnvironment.","Gate ssrLoadModule callers behind isRunnableDevEnvironment to fail fast with a clear message."],"tags":["ssr","environment","module-runner","api-migration"],"analyzedSha":"89620f09afcfef6b35e7bb8660132ab5b4d0cd3b","analyzedAt":"2026-08-03T19:28:02.920Z","schemaVersion":2}