{"record":{"id":"ab2c2d27036d56d8","repo":"withastro/astro","slug":"onlyresponsecanbereturned","errorCode":"OnlyResponseCanBeReturned","errorMessage":"Route `${route}` returned a `${returnedValue}`. Only a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) can be returned from Astro files.","messagePattern":"Route `(.+?)` returned a `(.+?)`\\. Only a \\[Response\\]\\(https://developer\\.mozilla\\.org/en-US/docs/Web/API/Response\\) can be returned from Astro files\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/runtime/server/render/astro/render.ts","lineNumber":323,"sourceCode":"}\n\nasync function callComponentAsTemplateResultOrResponse(\n\tresult: SSRResult,\n\tcomponentFactory: AstroComponentFactory,\n\tprops: any,\n\tchildren: any,\n\troute?: RouteData,\n) {\n\tconst factoryResult = await componentFactory(result, props, children);\n\n\tif (factoryResult instanceof Response) {\n\t\treturn factoryResult;\n\t}\n\t// we check if the component we attempt to render is a head+content\n\telse if (isHeadAndContent(factoryResult)) {\n\t\t// we make sure that content is valid template result\n\t\tif (!isRenderTemplateResult(factoryResult.content)) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.OnlyResponseCanBeReturned,\n\t\t\t\tmessage: AstroErrorData.OnlyResponseCanBeReturned.message(\n\t\t\t\t\troute?.route,\n\t\t\t\t\ttypeof factoryResult,\n\t\t\t\t),\n\t\t\t\tlocation: {\n\t\t\t\t\tfile: route?.component,\n\t\t\t\t},\n\t\t\t});\n\t\t}\n\n\t\t// return the content\n\t\treturn factoryResult.content;\n\t} else if (!isRenderTemplateResult(factoryResult)) {\n\t\tthrow new AstroError({\n\t\t\t...AstroErrorData.OnlyResponseCanBeReturned,\n\t\t\tmessage: AstroErrorData.OnlyResponseCanBeReturned.message(route?.route, typeof factoryResult),\n\t\t\tlocation: {","sourceCodeStart":305,"sourceCodeEnd":341,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/runtime/server/render/astro/render.ts#L305-L341","documentation":"When a page's component factory result is a head+content wrapper (`isHeadAndContent`), Astro expects the wrapper's `.content` to itself be a valid render-template result. If it isn't, the page returned something that is neither a `Response` nor a renderable template, so Astro throws `OnlyResponseCanBeReturned` with the route and the value's type. Pages must return a `Response` (or render normally without returning).","triggerScenarios":"A `.astro` page `return`s an object/value that wraps content incorrectly; a manually constructed head+content-like structure with a malformed `.content`; returning a non-Response, non-template value from page frontmatter.","commonSituations":"Returning a custom object or string from `.astro` frontmatter expecting it to be the response body; interfering with Astro's internal content wrappers via an integration.","solutions":["Do not return arbitrary values from an Astro page; render markup normally or return a `Response`.","To send a redirect or custom status, `return new Response(null, { status, headers })` or `return Astro.redirect(...)`.","If you construct head+content structures manually (integration/plugin), ensure `.content` is a render-template result."],"exampleFix":"// before — page returns a plain object\n---\nreturn { html: '<p>hi</p>' };\n---\n\n// after — return a Response\n---\nreturn new Response('<p>hi</p>', { headers: { 'content-type': 'text/html' } });\n---","handlingStrategy":"validation","validationCode":"// Ensure page frontmatter only returns a Response (or nothing)\nfunction assertPageReturn(value: unknown): Response | void {\n  if (value instanceof Response) return value;\n  if (value === undefined) return;\n  throw new Error('Astro pages may only return a Response');\n}","typeGuard":"const isPageResponse = (v: unknown): v is Response => v instanceof Response;","tryCatchPattern":null,"preventionTips":["Never `return` raw data from an `.astro` page; render it instead.","Use API endpoints (handler exports) for data-only responses.","If returning from a page, return only a `Response`."],"tags":["page","response","render","astro-file"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}