{"record":{"id":"1e884bb44ef7ddbc","repo":"withastro/astro","slug":"middlewarenotaresponse","errorCode":"MiddlewareNotAResponse","errorMessage":"Any data returned from middleware must be a valid `Response` object.","messagePattern":"Any data returned from middleware must be a valid `Response` object\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/middleware/callMiddleware.ts","lineNumber":76,"sourceCode":"\t};\n\n\tconst middlewarePromise = onRequest(apiContext, next);\n\n\treturn await Promise.resolve(middlewarePromise).then(async (value) => {\n\t\t// first we check if `next` was called\n\t\tif (nextCalled) {\n\t\t\t/**\n\t\t\t * Then we check if a value is returned. If so, we need to return the value returned by the\n\t\t\t * middleware.\n\t\t\t * e.g.\n\t\t\t * ```js\n\t\t\t * \tconst response = await next();\n\t\t\t * \tconst new Response(null, { status: 500, headers: response.headers });\n\t\t\t * ```\n\t\t\t */\n\t\t\tif (typeof value !== 'undefined') {\n\t\t\t\tif (value instanceof Response === false) {\n\t\t\t\t\tthrow new AstroError(AstroErrorData.MiddlewareNotAResponse);\n\t\t\t\t}\n\t\t\t\treturn value;\n\t\t\t} else {\n\t\t\t\t/**\n\t\t\t\t * Here we handle the case where `next` was called and returned nothing.\n\t\t\t\t */\n\t\t\t\tif (responseFunctionPromise) {\n\t\t\t\t\treturn responseFunctionPromise;\n\t\t\t\t} else {\n\t\t\t\t\tthrow new AstroError(AstroErrorData.MiddlewareNotAResponse);\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (typeof value === 'undefined') {\n\t\t\t/**\n\t\t\t * There might be cases where `next` isn't called and the middleware **must** return\n\t\t\t * something.\n\t\t\t *\n\t\t\t * If not thing is returned, then we raise an Astro error.","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/core/middleware/callMiddleware.ts#L58-L94","documentation":"callMiddleware enforces the middleware contract: a middleware that calls next() may return nothing (the response from next is used) or must return a Response instance. This branch throws AstroErrorData.MiddlewareNotAResponse when next() was called and the middleware returned a defined value that fails `value instanceof Response` — a plain object, string, or a Response created in another runtime/Realm (e.g. a node-fetch or cross-realm Response).","triggerScenarios":"A middleware that does `const res = await next(); return { ...res }` or returns a status object like { status: 500 }; returning a Response produced by a fetch polyfill or another Realm so the instanceof check against the global Response fails.","commonSituations":"Copying Express middleware patterns that return plain result objects; using node-fetch or an older undici alongside the global fetch in the same process; middleware returning response.json() or a mutated copy of headers instead of the Response itself.","solutions":["Return the Response you got: `const res = await next(); return res;`","Build a real Response when transforming: return new Response(body, { status, headers })","Remove fetch polyfills from server code so instanceof checks use the global Response"],"exampleFix":"// before\nexport const onRequest = async (context, next) => {\n  const response = await next();\n  if (!response.ok) return { status: 500 };\n  return response;\n};\n\n// after\nexport const onRequest = async (context, next) => {\n  const response = await next();\n  if (!response.ok) return new Response('error', { status: 500 });\n  return response;\n};","handlingStrategy":"validation","validationCode":"const result = await next();\nif (!(result instanceof Response)) {\n  throw new TypeError('Middleware returned a non-Response value after next()');\n}\nreturn result;","typeGuard":"const isResponse = (value: unknown): value is Response => value instanceof Response;","tryCatchPattern":null,"preventionTips":["Default to `return await next()` in every middleware that does not short-circuit","When transforming the response, always rebuild with new Response(body, { status, headers })","Avoid fetch polyfills in server code so instanceof Response checks are consistent"],"tags":["middleware","response","instanceof","return-type"],"backgroundTag":"middleware-invalid-return-type","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"}