withastro/astro · error · AstroError

SessionStorageInitError

SessionStorageInitError

Error message

Error when initializing session storage. `No driver was defined in the session configuration and the adapter did not provide a default driver.`

What it means

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.

Solutions

1. Configure a driver in astro.config.mjs: session: { driver: 'fs', options: { base: './.astro/sessions' } } (fs is built in via unstorage).
2. Or use an adapter that provides a default session driver (e.g. platform drivers), so no explicit driver is needed.
3. Guard code that touches sessions so it only runs when a driver is configured (sessions are unavailable otherwise).

Example fix

// before
export default defineConfig({ output: 'server', adapter: node() });
// Astro.session.get('cart') throws

// after
export default defineConfig({
  output: 'server',
  adapter: node(),
  session: { driver: 'fs', options: { base: './.astro/sessions' } },
});

// astro.config.mjs
const usesSessions = process.env_FEATURE_SESSIONS === '1';
export default defineConfig({
  ...(usesSessions && { session: { driver: 'fs', options: { base: './.astro/sessions' } } }),
});

When it happens

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

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

Related errors

• SessionStorageInitError
• SessionStorageSaveError
• CacheNotEnabled
• Entry → was not found.
• RemoteImageNotAllowed

AI-assisted analysis of withastro/astro@3578d45d34 (2026-08-18). Data as JSON: /api/errors/72e36f14bfdf4afd. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/core/session/runtime.ts:90

	// When we load the data from storage, we need to merge it with the local partial data,
	// preserving in-memory changes and deletions.
	#partial = true;
	#logger: AstroLogger;
	#driverFactory: SessionDriverFactory | null;

	static #sharedStorage = new Map<string, Storage>();

	constructor({
		cookies,
		config,
		runtimeMode,
		driverFactory,
		mockStorage,
		logger,
	}: AstroSessionOptions) {
		this.#logger = logger;
		if (!config) {
			throw new AstroError({
				...SessionStorageInitError,
				message: SessionStorageInitError.message(
					'No driver was defined in the session configuration and the adapter did not provide a default driver.',
				),
			});
		}
		this.#cookies = cookies;
		this.#driverFactory = driverFactory;
		const { cookie: cookieConfig = DEFAULT_COOKIE_NAME, ...configRest } = config;
		let cookieConfigObject: AstroCookieSetOptions | undefined;
		if (typeof cookieConfig === 'object') {
			const { name = DEFAULT_COOKIE_NAME, ...rest } = cookieConfig;
			this.#cookieName = name;
			cookieConfigObject = rest;
		} else {
			this.#cookieName = cookieConfig || DEFAULT_COOKIE_NAME;
		}
		this.#cookieConfig = {

View on GitHub (pinned to 3578d45d34)