{"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/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/runtime/server/render/astro/render.ts#L305-L341","documentation":"renderPage validates the value produced by a page component: allowed outcomes are a Response (redirect/404), a HeadAndContent wrapper whose content is a valid RenderTemplateResult, or a RenderTemplateResult itself (what the compiled .astro body normally produces). This site fires when the factory result is HeadAndContent but its content is not a render template, i.e. the page returned structured data where markup was required.","triggerScenarios":"An .astro frontmatter returning a non-Response, non-template value that gets wrapped as head+content: return someObject, return null after a guard clause, or a layout/content combination whose content is data instead of template output.","commonSituations":"Treating .astro frontmatter like an endpoint (return data); early-return pattern 'if (!post) return;' with no value; returning the result of a helper that yields plain objects; porting pages from frameworks where returning strings/objects from pages is normal.","solutions":["Return a Response for control flow: return new Response(null, { status: 404 }) or Astro.redirect(...)","Otherwise return nothing and let the page template render","Move pure data endpoints to a .js/.ts API route file instead of an .astro page"],"exampleFix":"// before\n---\nconst post = await getPost(Astro.params.slug);\nif (!post) return null;\n---\n\n// after\n---\nconst post = await getPost(Astro.params.slug);\nif (!post) return new Response(null, { status: 404 });\n---","handlingStrategy":"type-guard","validationCode":"// in wrappers that return page results, assert the shape\nconst result = await loadPageResult();\nif (!(result instanceof Response)) {\n  throw new Error('Page must return a Response or render its template');\n}","typeGuard":"function isResponse(value: unknown): value is Response {\n  return value instanceof Response;\n}","tryCatchPattern":null,"preventionTips":["In .astro frontmatter, either return a Response (Astro.redirect, 404) or return nothing","Never 'return;' bare or return data objects from pages","Serve data-only routes from .js/.ts endpoint files, not .astro pages"],"tags":["astro","page","return-type","response","ssr"],"backgroundTag":"page-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"}