sveltejs/kit · error · Error

The configured Vite SSR environment must be a RunnableDevEnv

Error message

The configured Vite SSR environment must be a RunnableDevEnvironment

What it means

SvelteKit loads server modules through the Vite SSR environment's runner. Because `isRunnableDevEnvironment` uses an instanceof check against the Vite copy SvelteKit uses, an SSR environment created by a different Vite instance (or one that is not runnable, e.g. a custom environment) fails the check and throws.

Source

Thrown at packages/kit/src/runner.js:12

/** @import * as vite from 'vite' */
/** @import { ViteDevServer } from 'vite' */

/**
 * @param {typeof vite} vite the vite module that created the server
 * @param {ViteDevServer} server
 */
export function get_runner({ isRunnableDevEnvironment }, server) {
	// `isRunnableDevEnvironment` does an `instanceof` check and will fail if
	// we're using different instances of Vite
	if (!isRunnableDevEnvironment(server.environments.ssr)) {
		throw new Error('The configured Vite SSR environment must be a RunnableDevEnvironment');
	}

	return server.environments.ssr.runner;
}

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Deduplicate Vite so a single version/instance is used: `pnpm why vite` / `npm ls vite`, fix overrides, reinstall
2. Ensure the SSR environment is runnable: in vite.config use `environments.ssr.dev ??= {}` or import `createRunnableDevEnvironment` if using custom environments
3. Align the Vite version with the range required by @sveltejs/kit and update both packages
4. Clear lockfile/dedupe issues (`pnpm dedupe`, regenerate lockfile)

Example fix

// before (vite.config.ts)
environments: { ssr: createDevEnvironment('ssr') }
// after
import { createRunnableDevEnvironment } from 'vite';
environments: { ssr: createRunnableDevEnvironment('ssr') }

import { isRunnableDevEnvironment } from 'vite';
if (!isRunnableDevEnvironment(server.environments.ssr)) {
  throw new Error('vite.config must define a runnable SSR environment');
}

const isRunnableSSR = (server, isRunnableDevEnvironment) =>
  Boolean(server?.environments?.ssr) && isRunnableDevEnvironment(server.environments.ssr);

try {
  const runner = get_runner({ isRunnableDevEnvironment }, server);
} catch (e) {
  if (/RunnableDevEnvironment/.test(e.message)) {
    throw new Error('Deduplicate Vite and use a RunnableDevEnvironment for ssr');
  }
  throw e;
}

When it happens

Trigger: get_runner is called with a vite dev server whose environments.ssr is not a RunnableDevEnvironment from the same Vite module instance — e.g. a custom vite.config environment setup, Vite version mismatch, or duplicated Vite installations.

Common situations: pnpm/npm dependency duplication causing two Vite copies, custom environments (non-runnable SSR environment) configured in vite.config, mixing Vite major versions, or plugin-based environment overrides.

Related errors

• ${manifest_error.message ?? 'Invalid routes'}
• Cannot access cloudflare:workers in a prerenderable route
• @sveltejs/enhanced-img requires @sveltejs/vite-plugin-svelte
• Could not locate ${file_path}. Please move it to be located
• Could not locate ${file_path}. See https://vitejs.dev/guide/

AI-assisted analysis of sveltejs/kit@03f1687fe6 (2026-09-02). Data as JSON: /api/errors/58193e836e9c9e9c. Report an issue: GitHub.