{"record":{"id":"e44a39f070b7f400","repo":"withastro/astro","slug":"sessionstorageiniterror-e44a39","errorCode":"SessionStorageInitError","errorMessage":"Error when initializing session storage with driver `${driver}`. `Failed to resolve session driver: ${driver.entrypoint}`","messagePattern":"Error when initializing session storage with driver `(.+?)`\\. `Failed to resolve session driver: (.+?)`","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/session/vite-plugin.ts","lineNumber":41,"sourceCode":"\t\t\t\treturn RESOLVED_VIRTUAL_SESSION_DRIVER_ID;\n\t\t\t},\n\t\t},\n\n\t\tload: {\n\t\t\tfilter: {\n\t\t\t\tid: new RegExp(`^${RESOLVED_VIRTUAL_SESSION_DRIVER_ID}$`),\n\t\t\t},\n\t\t\tasync handler() {\n\t\t\t\tconst session = settings.config.session;\n\t\t\t\tif (session === false || !session?.driver) {\n\t\t\t\t\treturn { code: 'export default null;' };\n\t\t\t\t}\n\n\t\t\t\tconst driver = normalizeSessionDriverConfig(session.driver, session.options);\n\t\t\t\tconst importerPath = fileURLToPath(import.meta.url);\n\t\t\t\tconst resolved = await this.resolve(driver.entrypoint, importerPath);\n\t\t\t\tif (!resolved) {\n\t\t\t\t\tthrow new AstroError({\n\t\t\t\t\t\t...SessionStorageInitError,\n\t\t\t\t\t\tmessage: SessionStorageInitError.message(\n\t\t\t\t\t\t\t`Failed to resolve session driver: ${driver.entrypoint}`,\n\t\t\t\t\t\t\tdriver.entrypoint,\n\t\t\t\t\t\t),\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\treturn {\n\t\t\t\t\tcode: `import { default as _default } from '${resolved.id}';\\nexport * from '${resolved.id}';\\nexport default _default;`,\n\t\t\t\t};\n\t\t\t},\n\t\t},\n\t};\n}\n\n// When no session driver will be present at request time, swap Astro's own\n// `core/session/provider.js` for `core/session/provider-disabled.js` so","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/core/session/vite-plugin.ts#L23-L59","documentation":"At build/dev time the session Vite plugin generates a virtual module that imports your driver: normalizeSessionDriverConfig maps the configured name ('fs' and friends to unstorage builtin entrypoints, anything else treated as a package path/URL) and then this.resolve(driver.entrypoint, importerPath) must resolve it. When resolution fails, SessionStorageInitError 'Failed to resolve session driver: ${entrypoint}' is thrown — the driver module literally cannot be found from Astro's location.","triggerScenarios":"session: { driver: 'redis-server' } where no such package exists (typo); naming a driver package that is not installed (driver: 'unstorage/drivers/upstash' without unstorage present at the right version, or a custom './src/driver.ts' path that does not exist); driver names that are neither unstorage builtins nor resolvable relative/absolute paths.","commonSituations":"Assuming a driver name auto-installs its package (it does not — install it yourself); relative entrypoint paths resolved against the wrong base (use the object form with entrypoint); monorepos where the driver package is installed in a different workspace than packages/astro resolves from; typos like 'rediss' or 'fs-lite' vs 'fsLite' mismatches.","solutions":["Install the driver package in the project: pnpm add unstorage (builtin drivers) or your custom driver package.","Fix the name/typo: use exact unstorage driver names ('fs', 'redis', 'http', ...) or a valid module path.","For local files, use the object form so the path is explicit: driver: { entrypoint: new URL('./src/drivers/my-driver.ts', import.meta.url) }."],"exampleFix":"// before\nexport default defineConfig({\n  session: { driver: 'unstorage/drivers/redis' }, // unstorage not installed\n});\n\n// after\n// pnpm add unstorage\nexport default defineConfig({\n  session: { driver: 'redis', options: { url: process.env.REDIS_URL } },\n});","handlingStrategy":"validation","validationCode":"// prebuild check: every driver entrypoint must resolve\nimport { createRequire } from 'node:module';\nimport { builtinDrivers } from 'unstorage';\n\nconst require = createRequire(import.meta.url);\nconst driverName = 'redis';\nconst entrypoint =\n  driverName in builtinDrivers ? builtinDrivers[driverName] : driverName;\n\nrequire.resolve(entrypoint); // throws with a precise message if not installed","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install the driver's package yourself — Astro does not auto-install drivers.","Use exact unstorage driver names, or the object form with an explicit entrypoint path/URL.","Add a resolve smoke test to your build pipeline to catch missing drivers before Vite does."],"tags":["astro","sessions","session-driver","module-resolution","vite-plugin","build-time"],"backgroundTag":"cannot-resolve-module","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}