{"record":{"id":"58193e836e9c9e9c","repo":"sveltejs/kit","slug":"the-configured-vite-ssr-environment-must-be-a-runn","errorCode":null,"errorMessage":"The configured Vite SSR environment must be a RunnableDevEnvironment","messagePattern":"The configured Vite SSR environment must be a RunnableDevEnvironment","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/kit/src/runner.js","lineNumber":12,"sourceCode":"/** @import * as vite from 'vite' */\n/** @import { ViteDevServer } from 'vite' */\n\n/**\n * @param {typeof vite} vite the vite module that created the server\n * @param {ViteDevServer} server\n */\nexport function get_runner({ isRunnableDevEnvironment }, server) {\n\t// `isRunnableDevEnvironment` does an `instanceof` check and will fail if\n\t// we're using different instances of Vite\n\tif (!isRunnableDevEnvironment(server.environments.ssr)) {\n\t\tthrow new Error('The configured Vite SSR environment must be a RunnableDevEnvironment');\n\t}\n\n\treturn server.environments.ssr.runner;\n}\n","sourceCodeStart":1,"sourceCodeEnd":17,"githubUrl":"https://github.com/sveltejs/kit/blob/03f1687fe612ce3d2d9131139b5b188d9cf90c64/packages/kit/src/runner.js#L1-L17","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Deduplicate Vite so a single version/instance is used: `pnpm why vite` / `npm ls vite`, fix overrides, reinstall","Ensure the SSR environment is runnable: in vite.config use `environments.ssr.dev ??= {}` or import `createRunnableDevEnvironment` if using custom environments","Align the Vite version with the range required by @sveltejs/kit and update both packages","Clear lockfile/dedupe issues (`pnpm dedupe`, regenerate lockfile)"],"exampleFix":"// before (vite.config.ts)\nenvironments: { ssr: createDevEnvironment('ssr') }\n// after\nimport { createRunnableDevEnvironment } from 'vite';\nenvironments: { ssr: createRunnableDevEnvironment('ssr') }","handlingStrategy":"validation","validationCode":"import { isRunnableDevEnvironment } from 'vite';\nif (!isRunnableDevEnvironment(server.environments.ssr)) {\n  throw new Error('vite.config must define a runnable SSR environment');\n}","typeGuard":"const isRunnableSSR = (server, isRunnableDevEnvironment) =>\n  Boolean(server?.environments?.ssr) && isRunnableDevEnvironment(server.environments.ssr);","tryCatchPattern":"try {\n  const runner = get_runner({ isRunnableDevEnvironment }, server);\n} catch (e) {\n  if (/RunnableDevEnvironment/.test(e.message)) {\n    throw new Error('Deduplicate Vite and use a RunnableDevEnvironment for ssr');\n  }\n  throw e;\n}","preventionTips":["Run `npm ls vite` / `pnpm why vite` to ensure a single Vite instance","Use createRunnableDevEnvironment when defining custom SSR environments in vite.config","Pin Vite to a version compatible with your @sveltejs/kit release","Dedupe dependencies after lockfile changes"],"tags":["vite","ssr","dev-server","dependency-mismatch"],"backgroundTag":"vite-environment-not-runnable","analyzedSha":"03f1687fe612ce3d2d9131139b5b188d9cf90c64","analyzedAt":"2026-09-02T02:01:50.504Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}