{"record":{"id":"72e36f14bfdf4afd","repo":"withastro/astro","slug":"sessionstorageiniterror","errorCode":"SessionStorageInitError","errorMessage":"Error when initializing session storage. `No driver was defined in the session configuration and the adapter did not provide a default driver.`","messagePattern":"Error when initializing session storage\\. `No driver was defined in the session configuration and the adapter did not provide a default driver\\.`","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/session/runtime.ts","lineNumber":90,"sourceCode":"\t// When we load the data from storage, we need to merge it with the local partial data,\n\t// preserving in-memory changes and deletions.\n\t#partial = true;\n\t#logger: AstroLogger;\n\t#driverFactory: SessionDriverFactory | null;\n\n\tstatic #sharedStorage = new Map<string, Storage>();\n\n\tconstructor({\n\t\tcookies,\n\t\tconfig,\n\t\truntimeMode,\n\t\tdriverFactory,\n\t\tmockStorage,\n\t\tlogger,\n\t}: AstroSessionOptions) {\n\t\tthis.#logger = logger;\n\t\tif (!config) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...SessionStorageInitError,\n\t\t\t\tmessage: SessionStorageInitError.message(\n\t\t\t\t\t'No driver was defined in the session configuration and the adapter did not provide a default driver.',\n\t\t\t\t),\n\t\t\t});\n\t\t}\n\t\tthis.#cookies = cookies;\n\t\tthis.#driverFactory = driverFactory;\n\t\tconst { cookie: cookieConfig = DEFAULT_COOKIE_NAME, ...configRest } = config;\n\t\tlet cookieConfigObject: AstroCookieSetOptions | undefined;\n\t\tif (typeof cookieConfig === 'object') {\n\t\t\tconst { name = DEFAULT_COOKIE_NAME, ...rest } = cookieConfig;\n\t\t\tthis.#cookieName = name;\n\t\t\tcookieConfigObject = rest;\n\t\t} else {\n\t\t\tthis.#cookieName = cookieConfig || DEFAULT_COOKIE_NAME;\n\t\t}\n\t\tthis.#cookieConfig = {","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/withastro/astro/blob/3578d45d34226d63cff3d261c971c221de6794d2/packages/astro/src/core/session/runtime.ts#L72-L108","documentation":"AstroSession's constructor requires a session storage driver, sourced either from the session config (session.driver in astro.config) or from a default provided by the active adapter. When the resolved config object is falsy — no session.driver configured and no adapter default — the constructor throws SessionStorageInitError with 'No driver was defined...' before any session operation can run. Sessions cannot work without a backing store, so this fails fast on first access to Astro.session/context.session.","triggerScenarios":"Calling Astro.session.get('user') or context.session.set(...) in a page/middleware/API route when astro.config.mjs has no session: { driver: ... } block and the installed adapter supplies no default driver (e.g. static output, or an adapter without session support).","commonSituations":"Following a sessions tutorial but skipping the config step; using sessions with output: 'static'; an adapter that does not implement default session storage; config merge (environment overrides) dropping the session key.","solutions":["Configure a driver in astro.config.mjs: session: { driver: 'fs', options: { base: './.astro/sessions' } } (fs is built in via unstorage).","Or use an adapter that provides a default session driver (e.g. platform drivers), so no explicit driver is needed.","Guard code that touches sessions so it only runs when a driver is configured (sessions are unavailable otherwise)."],"exampleFix":"// before\nexport default defineConfig({ output: 'server', adapter: node() });\n// Astro.session.get('cart') throws\n\n// after\nexport default defineConfig({\n  output: 'server',\n  adapter: node(),\n  session: { driver: 'fs', options: { base: './.astro/sessions' } },\n});","handlingStrategy":"validation","validationCode":"// astro.config.mjs\nconst usesSessions = process.env_FEATURE_SESSIONS === '1';\nexport default defineConfig({\n  ...(usesSessions && { session: { driver: 'fs', options: { base: './.astro/sessions' } } }),\n});","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Configure session.driver the moment you first reference Astro.session in code.","Use the built-in 'fs' driver for local dev and a platform driver for prod.","Remember output:'static' has no runtime — sessions need an adapter."],"tags":["astro","sessions","configuration","session-driver","runtime"],"backgroundTag":"missing-session-driver","analyzedSha":"3578d45d34226d63cff3d261c971c221de6794d2","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}