vitejs/vite · error · Error

ssrLoadModule requires the 'ssr' environment to be a…

Error message

ssrLoadModule requires the 'ssr' environment to be a runnable environment.

What it means

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.

Solutions

1. Let Vite create the default ssr environment (do not override server.environments.ssr) if you need ssrLoadModule.
2. If you customize environments, create the ssr one with RunnableDevEnvironment (createRunnableDevEnvironment / createServerEnvironment with the runnable kind).
3. For new code, prefer using the module runner directly (createServerModuleRunner) instead of ssrLoadModule when working with custom environments.

Example fix

// before: ssr env replaced with a non-runnable environment
environments.ssr = new DevEnvironment('ssr', config, {})
server.ssrLoadModule('/entry.js') // throws
// after: keep a runnable ssr environment (the default)
// don't override environments.ssr, or use createServerEnvironment with runnable runner

import { isRunnableDevEnvironment } from 'vite'
if (!isRunnableDevEnvironment(server.environments.ssr)) {
  throw new Error('ssr environment is not runnable; cannot ssrLoadModule')
}

import { isRunnableDevEnvironment } from 'vite'
function assertRunnable(env: Environment): asserts env is RunnableDevEnvironment {
  if (!isRunnableDevEnvironment(env)) throw new Error('not a runnable environment')
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot send non-custom events from the client to the server.
• Cannot send non-custom events from the server to the client.
• [module runner] Dynamic access of "import.meta.env" is not…
• [module runner] Failed to load
• [module runner] "import.meta.glob" is statically replaced…

AI-assisted analysis of vitejs/vite@b4d66fee14 (2026-08-11). Data as JSON: /api/errors/03d91e6c30c67044. Report an issue: GitHub.

Appendix: source

Thrown at packages/vite/src/node/ssr/ssrModuleLoader.ts:26

import type { ViteDevServer } from '../server'
import { unwrapId } from '../../shared/utils'
import type { DevEnvironment } from '../server/environment'
import type { NormalizedServerHotChannel } from '../server/hmr'
import { buildErrorMessage } from '../server/middlewares/error'
import { isRunnableDevEnvironment } from '../../node'
import { ssrFixStacktrace } from './ssrStacktrace'
import { createServerModuleRunnerTransport } from './runtime/serverModuleRunner'

type SSRModule = Record<string, any>

export async function ssrLoadModule(
  url: string,
  server: ViteDevServer,
  fixStacktrace?: boolean,
): Promise<SSRModule> {
  const environment = server.environments.ssr
  if (!isRunnableDevEnvironment(environment)) {
    throw new Error(
      `ssrLoadModule requires the 'ssr' environment to be a runnable environment.`,
    )
  }
  server._ssrCompatModuleRunner ||= new SSRCompatModuleRunner(environment)
  url = unwrapId(url)

  return instantiateModule(
    url,
    server._ssrCompatModuleRunner,
    environment,
    fixStacktrace,
  )
}

async function instantiateModule(
  url: string,
  runner: ModuleRunner,
  environment: DevEnvironment,

View on GitHub (pinned to b4d66fee14)