withastro/astro · warning

Using deprecated `session.driver` string signature. Learn ho

Error message

Using deprecated `session.driver` string signature. Learn how to migrate: https://docs.astro.build/en/guides/upgrade-to/v6/#deprecated-session-driver-string-signature

What it means

Astro 6 structures session.driver as an object ({ entrypoint, config }); the zod schema still accepts the legacy string form but its superRefine runs a plain console.warn flagging the deprecation with the v6 migration link. It fires during config parsing, once per validation, on every dev start, build, or config reload that still uses the string.

Source

Thrown at packages/astro/src/core/session/config.ts:12

import * as z from 'zod/v4';

export const SessionDriverConfigSchema = z.object({
	config: z.record(z.string(), z.any()).optional(),
	entrypoint: z.union([z.string(), z.instanceof(URL)]),
});

const SessionObjectSchema = z.object({
	driver: z
		.union([
			z.string().superRefine(() => {
				console.warn(
					`Using deprecated \`session.driver\` string signature. Learn how to migrate: https://docs.astro.build/en/guides/upgrade-to/v6/#deprecated-session-driver-string-signature`,
				);
			}),
			SessionDriverConfigSchema,
		])
		.optional(),
	options: z.record(z.string(), z.any()).optional(),
	cookie: z
		.union([
			z.object({
				name: z.string().optional(),
				domain: z.string().optional(),
				path: z.string().optional(),
				maxAge: z.number().optional(),
				sameSite: z.union([z.enum(['strict', 'lax', 'none']), z.boolean()]).optional(),
				secure: z.boolean().optional(),
			}),
			z.string().transform((name) => ({ name })),

View on GitHub (pinned to 52e6c34790)

Solutions

1. Replace the string with the object form, e.g. driver: { entrypoint: 'astro/session/drivers/file', config: { path: './.session' } }
2. Follow the linked v6 migration section for the driver you use
3. Restart astro dev afterwards and confirm the warning is gone

Example fix

// astro.config.mjs — before
session: { driver: 'fs', options: { path: './.session' } },

// after
session: {
  driver: {
    entrypoint: 'astro/session/drivers/file',
    config: { path: './.session' },
  },
},

const driver = astroConfig.session?.driver;
if (typeof driver === 'string') {
  throw new Error('session.driver string form is deprecated — migrate to { entrypoint, config }');
}

function isLegacyDriver(d: unknown): d is string {
  return typeof d === 'string';
}

When it happens

Trigger: astro.config contains session: { driver: 'fs' } (or any string) instead of { driver: { entrypoint: ..., config: ... } }.

Common situations: Upgrading to Astro 6 with a v5-era session config; copying pre-v6 docs or blog snippets; CI logs filling with the warning on each cold start.

Related errors

• Auto-generating collections for folders in "src/content/" t
• [astro] ${names} ${isPlural ? 'are' : 'is'} deprecated. Move
• The adapter ${adapterName} has deprecated its support for "$
• ${names} on `mdx({...})` ${isPlural ? 'are' : 'is'} deprecat
• `Astro.session` was accessed but no session storage is confi

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