withastro/astro · error · AstroError

SessionStorageInitError

SessionStorageInitError

Error message

Error when initializing session storage with driver `${driver}`. `Failed to resolve session driver: ${driver.entrypoint}`

What it means

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.

Solutions

1. Install the driver package in the project: pnpm add unstorage (builtin drivers) or your custom driver package.
2. Fix the name/typo: use exact unstorage driver names ('fs', 'redis', 'http', ...) or a valid module path.
3. For local files, use the object form so the path is explicit: driver: { entrypoint: new URL('./src/drivers/my-driver.ts', import.meta.url) }.

Example fix

// before
export default defineConfig({
  session: { driver: 'unstorage/drivers/redis' }, // unstorage not installed
});

// after
// pnpm add unstorage
export default defineConfig({
  session: { driver: 'redis', options: { url: process.env.REDIS_URL } },
});

// prebuild check: every driver entrypoint must resolve
import { createRequire } from 'node:module';
import { builtinDrivers } from 'unstorage';

const require = createRequire(import.meta.url);
const driverName = 'redis';
const entrypoint =
  driverName in builtinDrivers ? builtinDrivers[driverName] : driverName;

require.resolve(entrypoint); // throws with a precise message if not installed

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• NoAdapterInstalledServerIslands
• SessionStorageInitError
• Invalid route — brackets are unbalanced
• Invalid route — parameters must be separated
• Invalid route — rest parameter must be a standalone segment

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/e44a39f070b7f400. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/core/session/vite-plugin.ts:41

				return RESOLVED_VIRTUAL_SESSION_DRIVER_ID;
			},
		},

		load: {
			filter: {
				id: new RegExp(`^${RESOLVED_VIRTUAL_SESSION_DRIVER_ID}$`),
			},
			async handler() {
				const session = settings.config.session;
				if (session === false || !session?.driver) {
					return { code: 'export default null;' };
				}

				const driver = normalizeSessionDriverConfig(session.driver, session.options);
				const importerPath = fileURLToPath(import.meta.url);
				const resolved = await this.resolve(driver.entrypoint, importerPath);
				if (!resolved) {
					throw new AstroError({
						...SessionStorageInitError,
						message: SessionStorageInitError.message(
							`Failed to resolve session driver: ${driver.entrypoint}`,
							driver.entrypoint,
						),
					});
				}

				return {
					code: `import { default as _default } from '${resolved.id}';\nexport * from '${resolved.id}';\nexport default _default;`,
				};
			},
		},
	};
}

// When no session driver will be present at request time, swap Astro's own
// `core/session/provider.js` for `core/session/provider-disabled.js` so

View on GitHub (pinned to 52e6c34790)