withastro/astro · error · Error

Please use Astro.url instead.

Error message

Please use Astro.url instead.

What it means

In local dev, the Netlify adapter constructs a mock `Context` (Netlify Function context). `context.url` is defined as `get url(): never` that always throws, because Astro exposes the same data via `Astro.url`. Netlify's `url` field is intentionally unavailable to prevent divergence between the request URL and Astro's canonical URL.

Source

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

				// Import Deno polyfill for `process.env` at the top of the file
				js: 'import process from "node:process";',
			},
		});
	}

	function getLocalDevNetlifyContext(req: IncomingMessage): Context {
		const isHttps = req.headers['x-forwarded-proto'] === 'https';
		const parseBase64JSON = <T = unknown>(header: string): T | undefined => {
			if (typeof req.headers[header] === 'string') {
				try {
					return JSON.parse(Buffer.from(req.headers[header] as string, 'base64').toString('utf8'));
				} catch {}
			}
		};

		const context: Context = {
			get url(): never {
				throw new Error('Please use Astro.url instead.');
			},
			// The dev server is a long running process, so promises will run even with a noop
			waitUntil: () => {},
			account: parseBase64JSON('x-nf-account-info') ?? {
				id: 'mock-netlify-account-id',
			},
			deploy: {
				context: 'dev',
				id:
					typeof req.headers['x-nf-deploy-id'] === 'string'
						? req.headers['x-nf-deploy-id']
						: 'mock-netlify-deploy-id',
				published: false,
			},
			site: parseBase64JSON('x-nf-site-info') ?? {
				id: 'mock-netlify-site-id',
				name: 'mock-netlify-site.netlify.app',
				url: `${isHttps ? 'https' : 'http'}://localhost:${isRunningInNetlify ? 8888 : 4321}`,

View on GitHub (pinned to d081033d5f)

Solutions

1. Use `Astro.url` for the request URL.
2. If you need original Netlify context fields other than url/cookies/params/rewrite/next, read them from `context` directly.
3. Remove any code that destructures or serializes the whole `context` object in dev.

Example fix

// before
const url = context.url;

// after
const url = Astro.url;

function getRequestUrl(Astro: any): URL {
  // Never read context.url; prefer Astro.url
  return Astro.url;
}

function hasAstroUrl(Astro: any): Astro is { url: URL } {
  return Astro?.url instanceof URL;
}

When it happens

Trigger: Calling `Astro.locals.netlify.context.url` (or however the adapter exposes `context`) in dev. Code written for vanilla Netlify Functions that reads `context.url` and is reused inside an Astro handler. Logging/debugging that enumerates context keys.

Common situations: Porting Netlify Function code into Astro endpoints. Reading the whole context object for debugging (the getter throws on access).

Related errors

• Please use Astro.cookies instead.
• context.params don't contain any usable content in Astro.
• context.rewrite is not available in Astro.
• Astro.locals.runtime.ctx has been removed in Astro v6. Use '
• `context.next` is not implemented for serverless functions

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