vitejs/vite · error · Error

ssrLoadModule requires the 'ssr' environment to be a runnabl

Error message

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

What it means

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.

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 89620f09af)

Solutions

1. Use the module-runner API directly (create a ModuleRunner or use environment.runner if available) instead of ssrLoadModule.
2. Ensure the SSR environment is created as a RunnableDevEnvironment by providing a runner factory in the environment config.
3. If you rely on ssrLoadModule, confirm server.environments.ssr instanceof RunnableDevEnvironment before calling.

Example fix

// before
const mod = await server.ssrLoadModule('/src/entry-server.ts')

// after — check runnability, then use the runner
import { isRunnableDevEnvironment } from 'vite'
const ssrEnv = server.environments.ssr
if (isRunnableDevEnvironment(ssrEnv)) {
  const mod = await ssrEnv.runner.import('/src/entry-server.ts')
} else {
  throw new Error('SSR environment is not runnable; configure a runner factory')
}

import { isRunnableDevEnvironment } from 'vite'

const ssrEnv = server.environments.ssr
if (!isRunnableDevEnvironment(ssrEnv)) {
  throw new Error('Configure the ssr environment with a runner factory to use ssrLoadModule')
}
const mod = await server.ssrLoadModule(url)

import { isRunnableDevEnvironment } from 'vite'
import type { RunnableDevEnvironment } from 'vite'

function assertRunnable(env): asserts env is RunnableDevEnvironment {
  if (!isRunnableDevEnvironment(env)) {
    throw new Error(`Environment '${env.name}' is not runnable`)
  }
}

When it happens

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

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

Related errors

• [module runner] Dynamic access of "import.meta.env" is not s
• [module runner] "import.meta.resolve" is not supported.
• [module runner] "import.meta.glob" is statically replaced du
• Vite module runner has been closed.
• Module "${url}" was mistakenly invalidated during fetch phas

AI-assisted analysis of vitejs/vite@89620f09af (2026-08-03). Data as JSON: /data/errors/03d91e6c30c67044.json. Report an issue: GitHub.