withastro/astro · warning

`Astro.session` was accessed but no session storage is confi

Error message

`Astro.session` was accessed but no session storage is configured. Either configure the storage manually or use an adapter that provides session storage. For more information, see https://docs.astro.build/en/guides/sessions/

What it means

Astro defines `Astro.session` on the request context even when no session storage is wired into the pipeline; in that case it installs a getter that logs this warning once (domain 'session') and returns undefined. It exists so code touching `Astro.session` degrades visibly instead of throwing, pointing you to either configure storage or use an adapter that provides it.

Source

Thrown at packages/astro/src/core/fetch/fetch-state.ts:907

		if (this.#providers) {
			for (const key of this.#providers.keys()) {
				Object.defineProperty(target, key, {
					get: () => state.resolve(key),
					enumerable: true,
					configurable: true,
				});
			}
		}
		// Ensure `session` is always a defined property even when the
		// sessions handler is not part of the pipeline. Warns once on
		// access so users know they need to configure session storage.
		if (!this.#providers?.has('session')) {
			let warned = false;
			Object.defineProperty(target, 'session', {
				get() {
					if (!warned) {
						warned = true;
						state.logger.warn(
							'session',
							'`Astro.session` was accessed but no session storage is configured. ' +
								'Either configure the storage manually or use an adapter that provides session storage. ' +
								'For more information, see https://docs.astro.build/en/guides/sessions/',
						);
					}
					return undefined;
				},
				enumerable: true,
				configurable: true,
			});
		}
	}

	/**
	 * Resolves the route to use for this request and stores it on
	 * `this.routeData`. If the adapter (or the dev server) provided a
	 * `routeData` via render options it's already set and this is a

View on GitHub (pinned to e294953aa8)

Solutions

1. Add a top-level `session` config with a driver, e.g. session: { driver: { entrypoint: 'astro/session/drivers/file', config: { path: './.session' } } }
2. Switch to an adapter that provides session storage out of the box (for example @astrojs/node)
3. If sessions are not actually needed, remove the code reading Astro.session — it will only ever be undefined

Example fix

// astro.config.mjs — before
export default defineConfig({ output: 'server' }); // no session storage configured

// after
export default defineConfig({
  output: 'server',
  session: {
    driver: {
      entrypoint: 'astro/session/drivers/file',
      config: { path: './.session' },
    },
  },
});

const session = Astro.session;
if (session === undefined) {
  // no storage configured — take a non-session code path
} else {
  const user = await session.get('user');
}

function hasSession(astro: { session: unknown }): boolean {
  return astro.session !== undefined;
}

When it happens

Trigger: Reading `Astro.session` in a page, layout, middleware, or endpoint while the pipeline has no 'session' provider: no top-level `session` config in astro.config and an adapter that does not supply session storage (or no adapter at all).

Common situations: Running output 'static' with no adapter while middleware touches Astro.session; deploying with an adapter that lacks session support; starting to use sessions after an Astro upgrade before configuring a driver.

Related errors

• MissingMiddlewareForInternationalization
• [preview] No adapter found.
• IncorrectStrategyForI18n
• InvalidI18nMiddlewareConfiguration
• Setting the 'mode' option is required.

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