withastro/astro · error · AstroError

SessionStorageInitError

SessionStorageInitError

Error message

Failed to resolve session driver: ${driver.entrypoint}

What it means

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.

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 d081033d5f)

Solutions

1. Install the driver package the entrypoint points to (e.g. the relevant unstorage driver or @astrojs session driver package).
2. Correct the driver string to match an installed, resolvable module.
3. If using an alias, ensure it is configured in vite.resolve.alias / tsconfig paths.

Example fix

// before
export default defineConfig({ session: { driver: 'redis' } }); // package missing
// after
// npm install unstorage/drivers/redis-lite then:
export default defineConfig({ session: { driver: 'redis-lite' } });

import { existsSync } from 'node:fs';
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
function assertDriverResolvable(entrypoint) {
  try { require.resolve(entrypoint); }
  catch { throw new Error(`Session driver '${entrypoint}' cannot be resolved; install the package.`); }
}

const isResolvable = (specifier: string): boolean => {
  try { require.resolve(specifier); return true; } catch { return false; }
};

When it happens

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

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

Related errors

• MissingMiddlewareForInternationalization
• SessionStorageInitError
• EnvInvalidVariables
• [RSS] You can only glob entries within 'src/pages/' when pas
• [astro:actions] `defineAction()` unexpectedly used on the cl

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