withastro/astro · error · Error

`context.next` is not implemented for serverless functions

Error message

`context.next` is not implemented for serverless functions

What it means

next() on the Netlify Context chains to the next handler in an edge/function pipeline, a concept that does not exist in Astro's serverless functions. The dev Context implements it as a method that always throws, and the same operation is unsupported in the deployed Astro runtime.

Solutions

Model the chain as Astro middleware: export onRequest(context, next) and use Astro's next() to continue
Return a Response directly from the handler instead of delegating to a next handler
If you were using next() for auth gating, short-circuit with Astro.redirect before calling next()

Example fix

// before (Netlify edge style)
if (!authorized) return context.next();
// after (Astro middleware)
export const onRequest = async (context, next) => {
  if (!context.locals.authorized) return context.redirect('/login');
  return next();
};

Defensive patterns

Strategy: fallback

Validate before calling

// There is nothing to validate: next() is rejected by design. Replace the call site:
// Netlify chain style is not portable; use Astro middleware:
export const onRequest = async (context, next) => {
  if (!context.locals.user) return context.redirect('/login');
  return next();
};

Type guard

function isNetlifyNextAvailable(context: any): boolean {
  try {
    return typeof context?.next === 'function' && context.deploy?.context !== 'dev';
  } catch {
    return false;
  }
}

Try / catch

try {
  return await context.next();
} catch {
  return new Response('Not Found', { status: 404 });
}

Prevention

Express handler chains as Astro middleware, never via context.next()
Run shared Netlify helpers under astro dev; the stubs surface unsupported calls early
Return explicit Responses instead of delegating to a next handler

When it happens

Trigger: Calling context.next() inside an Astro page, endpoint, or middleware when the Netlify adapter is active (thrown by the local-dev stub; the operation has no deployed equivalent either).

Common situations: Edge middleware code migrated from Netlify where next() ends middleware and continues the chain; trying to implement fallback handlers by calling next() and reacting to the response.

Related errors

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

Appendix: source

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

			},
			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[];

	return {
		name: '@astrojs/netlify',
		hooks: {
			'astro:config:setup': async ({ config, updateConfig, logger, command }) => {

View on GitHub (pinned to 3578d45d34)