withastro/astro · error · Error

Please use Astro.cookies instead.

Error message

Please use Astro.cookies instead.

What it means

The mock dev Context built by getLocalDevNetlifyContext implements cookies as a throwing getter. Astro already exposes request cookies via Astro.cookies, so the adapter deliberately rejects context.cookies in local dev instead of returning a half-working duplicate.

Solutions

1. Use Astro.cookies.get(name) / Astro.cookies.set(...) in pages and API routes
2. In middleware use context.cookies (Astro's own middleware context), not the Netlify Context
3. Guard any remaining Netlify-specific cookie access with try/catch or restrict it to deployed functions

Example fix

// before
const session = locals.runtime.context.cookies.get('session');
// after
const session = Astro.cookies.get('session');

const ctx = locals.runtime?.context;
const isLocalDev = ctx?.deploy?.context === 'dev';
const session = isLocalDev ? Astro.cookies.get('session')?.value : ctx!.cookies.get?.('session');

function safeNetlifyCookies<T>(context: any, fallback: T): T {
  try {
    return (context.cookies ?? fallback) as T;
  } catch {
    return fallback;
  }
}

let cookies = Astro.cookies; // always available in Astro
try {
  cookies = locals.runtime.context.cookies; // throws in local dev
} catch {
  // keep Astro.cookies
}

When it happens

Trigger: Calling locals.runtime.context.cookies.get/set/... in a page, endpoint, or middleware while running under astro dev with the Netlify adapter.

Common situations: Netlify Functions snippets that use context.cookies; ported Next.js/Express cookie code wired to the Netlify Context; helper modules shared between functions and Astro routes.

Related errors

• `context.next` is not implemented for serverless functions
• context.params don't contain any usable content in Astro.
• context.rewrite is not available in Astro.
• Please use Astro.url instead.
• [astro:cache] Skipping cache for

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

Appendix: source

Thrown at packages/integrations/netlify/src/index.ts:596

				country: { code: 'mock', name: 'Mock Country' },
				subdivision: { code: 'SD', name: 'Mock Subdivision' },
				timezone: 'UTC',
				longitude: 0,
				latitude: 0,
			},
			ip:
				typeof req.headers['x-nf-client-connection-ip'] === 'string'
					? req.headers['x-nf-client-connection-ip']
					: (req.socket.remoteAddress ?? '127.0.0.1'),
			server: {
				region: 'local-dev',
			},
			requestId:
				typeof req.headers['x-nf-request-id'] === 'string'
					? req.headers['x-nf-request-id']
					: 'mock-netlify-request-id',
			get cookies(): never {
				throw new Error('Please use Astro.cookies instead.');
			},
			json: (input) => Response.json(input),
			log: console.info,
			next: () => {
				throw new Error('`context.next` is not implemented for serverless functions');
			},
			get params(): never {
				throw new Error("context.params don't contain any usable content in Astro.");
			},
			rewrite() {
				throw new Error('context.rewrite is not available in Astro.');
			},
		};

		return context;
	}

	let routes: IntegrationResolvedRoute[];

View on GitHub (pinned to 3578d45d34)