{"record":{"id":"e44a39f070b7f400","repo":"withastro/astro","slug":"sessionstorageiniterror-e44a39","errorCode":"SessionStorageInitError","errorMessage":"Failed to resolve session driver: ${driver.entrypoint}","messagePattern":"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/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/core/session/vite-plugin.ts#L23-L59","documentation":"The configured session.driver string must resolve to an importable module. The session Vite plugin throws AstroError code SessionStorageInitError when this.resolve(driver.entrypoint, importerPath) returns undefined — the module path could not be resolved.","triggerScenarios":"Setting `session: { driver: 'redis' }` without installing the driver package; a typo in the driver name; a relative/aliased path that Vite cannot resolve; the package is not a dependency of the project.","commonSituations":"Forgetting to `npm i` the driver; copy-pasting a driver name from docs that needs a separate install; using a monorepo alias that is not configured for Vite.","solutions":["Install the driver package the entrypoint points to (e.g. the relevant unstorage driver or @astrojs session driver package).","Correct the driver string to match an installed, resolvable module.","If using an alias, ensure it is configured in vite.resolve.alias / tsconfig paths."],"exampleFix":"// before\nexport default defineConfig({ session: { driver: 'redis' } }); // package missing\n// after\n// npm install unstorage/drivers/redis-lite then:\nexport default defineConfig({ session: { driver: 'redis-lite' } });","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nimport { createRequire } from 'node:module';\nconst require = createRequire(import.meta.url);\nfunction assertDriverResolvable(entrypoint) {\n  try { require.resolve(entrypoint); }\n  catch { throw new Error(`Session driver '${entrypoint}' cannot be resolved; install the package.`); }\n}","typeGuard":"const isResolvable = (specifier: string): boolean => {\n  try { require.resolve(specifier); return true; } catch { return false; }\n};","tryCatchPattern":null,"preventionTips":["Install the driver package before referencing it in session.driver.","Double-check the driver string spelling against installed packages.","Configure any path aliases in both tsconfig and vite.resolve.alias."],"tags":["session","config","build","driver"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}