{"record":{"id":"159737bb902df389","repo":"withastro/astro","slug":"the-integration-name-integration-is-trying-to-159737","errorCode":null,"errorMessage":"The \"${integration.name}\" integration is trying to add middleware but did not specify an order.","messagePattern":"The \"(.+?)\" integration is trying to add middleware but did not specify an order\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/integrations/hooks.ts","lineNumber":287,"sourceCode":"\t\t\t\t\t},\n\t\t\t\t\taddDevToolbarApp: (entrypoint) => {\n\t\t\t\t\t\tupdatedSettings.devToolbarApps.push(entrypoint);\n\t\t\t\t\t},\n\t\t\t\t\taddClientDirective: ({ name, entrypoint }) => {\n\t\t\t\t\t\tif (updatedSettings.clientDirectives.has(name) || addedClientDirectives.has(name)) {\n\t\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t\t`The \"${integration.name}\" integration is trying to add the \"${name}\" client directive, but it already exists.`,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// TODO: this should be performed after astro:config:done\n\t\t\t\t\t\taddedClientDirectives.set(\n\t\t\t\t\t\t\tname,\n\t\t\t\t\t\t\tbuildClientDirectiveEntrypoint(name, entrypoint, settings.config.root),\n\t\t\t\t\t\t);\n\t\t\t\t\t},\n\t\t\t\t\taddMiddleware: ({ order, entrypoint }) => {\n\t\t\t\t\t\tif (typeof updatedSettings.middlewares[order] === 'undefined') {\n\t\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t\t`The \"${integration.name}\" integration is trying to add middleware but did not specify an order.`,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tlogger.debug(\n\t\t\t\t\t\t\t'middleware',\n\t\t\t\t\t\t\t`The integration ${integration.name} has added middleware that runs ${\n\t\t\t\t\t\t\t\torder === 'pre' ? 'before' : 'after'\n\t\t\t\t\t\t\t} any application middleware you define.`,\n\t\t\t\t\t\t);\n\t\t\t\t\t\tupdatedSettings.middlewares[order].push(\n\t\t\t\t\t\t\ttypeof entrypoint === 'string' ? entrypoint : fileURLToPath(entrypoint),\n\t\t\t\t\t\t);\n\t\t\t\t\t},\n\t\t\t\t\tcreateCodegenDir: () => {\n\t\t\t\t\t\tconst codegenDir = new URL(normalizeCodegenDir(integration.name), settings.dotAstroDir);\n\t\t\t\t\t\tfs.mkdirSync(codegenDir, { recursive: true });\n\t\t\t\t\t\treturn codegenDir;\n\t\t\t\t\t},","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/integrations/hooks.ts#L269-L305","documentation":"Integrations can contribute middleware that runs before or after application middleware via `addMiddleware({ order, entrypoint })`. Astro stores these in slots keyed by order (`pre` and `post`); the callback throws this plain Error when `updatedSettings.middlewares[order]` is undefined - i.e. `order` is missing or is anything other than the literal strings 'pre' and 'post'.","triggerScenarios":"Calling addMiddleware({ entrypoint }) with no order; passing order: 'before', 'first', 'after' or any other string; building the options object dynamically so order ends up undefined.","commonSituations":"Authoring an integration that injects middleware and misremembering the API; copy-pasting from docs of other frameworks where order values differ; typos like 'Post' (case-sensitive).","solutions":["Pass order: 'pre' (runs before app middleware) or order: 'post' (runs after), exactly lowercase.","If the integration is third-party, update it or file an issue - the call site is inside the integration.","Type the argument ({ order, entrypoint }: { order: 'pre' | 'post'; entrypoint: string | URL }) so mistakes surface at compile time."],"exampleFix":"// before\naddMiddleware({ entrypoint: 'my-integration/middleware.js' }); // no order\n\n// after\naddMiddleware({ order: 'pre', entrypoint: 'my-integration/middleware.js' });","handlingStrategy":"validation","validationCode":"// inside an integration, before addMiddleware\nconst order = input.order as string | undefined;\nif (order !== 'pre' && order !== 'post') {\n  throw new Error('addMiddleware order must be exactly pre or post');\n}\naddMiddleware({ order, entrypoint });","typeGuard":"function isMiddlewareOrder(o: unknown): o is 'pre' | 'post' {\n  return o === 'pre' || o === 'post';\n}","tryCatchPattern":null,"preventionTips":["Type the options as { order: 'pre' | 'post'; entrypoint: string | URL }.","Remember order is lowercase and case-sensitive.","Test the setup hook with both orders so a bad value fails in CI, not in users' projects."],"tags":["integrations","middleware","plugin-api"],"backgroundTag":"invalid-integration-contract","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}