withastro/astro · error · AstroError

SessionStorageInitError

SessionStorageInitError

Error message

No driver was defined in the session configuration and the adapter did not provide a default driver.

What it means

Sessions require a configured storage driver. The AstroSession constructor throws AstroError code SessionStorageInitError when no session config was passed — i.e. there is no `session` block in astro.config.mjs and the active adapter did not provide a default driver, yet the sessions API was invoked.

Source

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

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

Solutions

1. Add a session block to astro.config: `session: { driver: 'fs' }` (or another unstorage driver).
2. Use an adapter that provides a default session driver.
3. Verify the config file being loaded is the one you edited (check for multiple configs).

Example fix

// astro.config.mjs before
export default defineConfig({ adapter: node() });
// after
export default defineConfig({ adapter: node(), session: { driver: 'fs' } });

import config from './astro.config.mjs';
if (!config.session || config.session === false || !config.session.driver) {
  throw new Error('Configure session.driver before using Astro.session (or use an adapter that provides a default driver).');
}

const hasSessionDriver = (cfg: any): boolean =>
  !!cfg.session && cfg.session !== false && !!cfg.session.driver;

When it happens

Trigger: Calling Astro.session.set/get on a project with no `session` configuration and an adapter that supplies no default driver (or with no adapter at all).

Common situations: Enabling sessions in page/middleware code before adding the session config; using an adapter without built-in session driver support; mis-naming the session key in config.

Related errors

• Configured image service is not a local service
• MissingGetFontFileRequestUrl
• [preview] No adapter found.
• SessionStorageInitError
• Renderer ${renderer.name} does not provide a serverEntrypoin

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