withastro/astro · error · Error

The "${integration.name}" integration is trying to add middl

Error message

The "${integration.name}" integration is trying to add middleware but did not specify an order.

What it means

`addMiddleware` reads `order` and uses it to index `updatedSettings.middlewares[order]` (which has fixed 'pre'/'post' keys). If `order` is undefined/invalid, `middlewares[order]` is undefined and Astro throws a plain Error telling you the integration did not specify an order.

Source

Thrown at packages/astro/src/integrations/hooks.ts:287

					},
					addDevToolbarApp: (entrypoint) => {
						updatedSettings.devToolbarApps.push(entrypoint);
					},
					addClientDirective: ({ name, entrypoint }) => {
						if (updatedSettings.clientDirectives.has(name) || addedClientDirectives.has(name)) {
							throw new Error(
								`The "${integration.name}" integration is trying to add the "${name}" client directive, but it already exists.`,
							);
						}
						// TODO: this should be performed after astro:config:done
						addedClientDirectives.set(
							name,
							buildClientDirectiveEntrypoint(name, entrypoint, settings.config.root),
						);
					},
					addMiddleware: ({ order, entrypoint }) => {
						if (typeof updatedSettings.middlewares[order] === 'undefined') {
							throw new Error(
								`The "${integration.name}" integration is trying to add middleware but did not specify an order.`,
							);
						}
						logger.debug(
							'middleware',
							`The integration ${integration.name} has added middleware that runs ${
								order === 'pre' ? 'before' : 'after'
							} any application middleware you define.`,
						);
						updatedSettings.middlewares[order].push(
							typeof entrypoint === 'string' ? entrypoint : fileURLToPath(entrypoint),
						);
					},
					createCodegenDir: () => {
						const codegenDir = new URL(normalizeCodegenDir(integration.name), settings.dotAstroDir);
						fs.mkdirSync(codegenDir, { recursive: true });
						return codegenDir;
					},

View on GitHub (pinned to d081033d5f)

Solutions

1. Provide `order: 'pre'` or `order: 'post'` in the object passed to `addMiddleware`.
2. Validate the integration's config so `order` is always one of the two allowed strings before calling the hook.
3. Update third-party integration packages that may target an older, order-optional API.

Example fix

// before
addMiddleware({ entrypoint: '@my/middleware' })

// after
addMiddleware({ order: 'pre', entrypoint: '@my/middleware' })

function assertMiddlewareOrder(entry) {
  if (entry.order !== 'pre' && entry.order !== 'post') {
    throw new Error('addMiddleware requires order: "pre" | "post"');
  }
}

function isMiddlewareOrder(value) {
  return value === 'pre' || value === 'post';
}

null

When it happens

Trigger: An integration calls `addMiddleware({ entrypoint })` without `order`, or with an `order` value other than `'pre'` or `'post'`.

Common situations: Authoring an integration that adds middleware and omitting the required `order` field; passing `order: undefined` from optional config; misunderstanding the API as order-optional.

Related errors

• MissingMiddlewareForInternationalization
• Integration ${integrationName} is injecting a type that does
• Integration ${integration.name} has an unnamed renderer.
• Renderer ${renderer.name} does not provide a serverEntrypoin
• The "${integration.name}" integration is trying to add the "

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