{"record":{"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/b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab/packages/vite/src/node/ssr/ssrModuleLoader.ts#L8-L44","documentation":"Thrown by ssrLoadModule() when server.environments.ssr is not a RunnableDevEnvironment. ssrLoadModule executes modules via a ModuleRunner, which only a runnable environment provides; a plain DevEnvironment cannot evaluate code.","triggerScenarios":"Calling server.ssrLoadModule(url) when the 'ssr' environment was created as a bare DevEnvironment or a FetchableDevEnvironment instead of RunnableDevEnvironment. The isRunnableDevEnvironment() guard is at ssrModuleLoader.ts:25.","commonSituations":"Custom environment setup that overrides environments.ssr with a non-runnable environment. Using the newer Environment API and replacing the default ssr environment. Migrating an integration that previously relied on the deprecated internal runner.","solutions":["Let Vite create the default ssr environment (do not override server.environments.ssr) if you need ssrLoadModule.","If you customize environments, create the ssr one with RunnableDevEnvironment (createRunnableDevEnvironment / createServerEnvironment with the runnable kind).","For new code, prefer using the module runner directly (createServerModuleRunner) instead of ssrLoadModule when working with custom environments."],"exampleFix":"// before: ssr env replaced with a non-runnable environment\nenvironments.ssr = new DevEnvironment('ssr', config, {})\nserver.ssrLoadModule('/entry.js') // throws\n// after: keep a runnable ssr environment (the default)\n// don't override environments.ssr, or use createServerEnvironment with runnable runner","handlingStrategy":"type-guard","validationCode":"import { isRunnableDevEnvironment } from 'vite'\nif (!isRunnableDevEnvironment(server.environments.ssr)) {\n  throw new Error('ssr environment is not runnable; cannot ssrLoadModule')\n}","typeGuard":"import { isRunnableDevEnvironment } from 'vite'\nfunction assertRunnable(env: Environment): asserts env is RunnableDevEnvironment {\n  if (!isRunnableDevEnvironment(env)) throw new Error('not a runnable environment')\n}","tryCatchPattern":null,"preventionTips":["Do not override server.environments.ssr with a non-runnable environment if you use ssrLoadModule.","Prefer the ModuleRunner API directly when customizing the ssr environment."],"tags":["ssr","environments","module-runner"],"backgroundTag":null,"analyzedSha":"b4d66fee14d970f45b8a6f3d7d6aee73ca9b88ab","analyzedAt":"2026-08-11T11:49:19.515Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}