Unable to return custom pages with a 404 status code

[cauboy]

Astro Info

$ npx astro info
Astro                    v4.16.14
Node                     v20.7.0
System                   macOS (arm64)
Package Manager          npm
Output                   server
Adapter                  @astrojs/node
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

I'm unable to return a page with a 404 status having custom content per URL. Whenever I set the status code to 404 either Astro's default 404 page or my custom 404 page is returned but never the content I intend to be returned. I cannot find a way to disable that behavior. When I return any other status code, e.g. a 410, things work as expected.

Use case:
In an online shop, when a product is no longer offered, I want to return a 404 status code under the product's URL for SEO reasons while still providing the user with custom content, i.e. the search results of similar articles.

Example:

---
// src/pages/products/[id].astro
if (Astro.params.id === 'sneaker-no-1') {
  Astro.response.status = 404
}
---
<Layout>
  <h1>We don't offer this product anymore</h1>
  <AlternativeProducts />
</Layout>

GET https://www.my-shop.com/products/sneaker-no-1

I want this URL to return a 404 Status with custom content containing search results for similar products.

Everything works if I returned a 410 Gone response instead, but I want to return a 404 because of SEO.

What's the expected result?

I expect to be able to to return customized 404 pages.

Link to Minimal Reproducible Example

https://idx.google.com/just-the-basics-6947654

Participation

• I am willing to submit a pull request for this issue.

[ematipico]

Just return a new Response from the frontmatter:

return new Response("not found", { 
  status: 404
})

Plus, Astro.response doesn't exist.

You can't return a 404 with the content you want.

Use the middleware in that case, where you can catch the response using const response = await next().

[cauboy]

@ematipico thanks for your answer.

I have a few questions related to it:

1. What's the reason that one cannot return a 404 with the content one wants?
2. Why does Astro have that restriction? In terms of SEO it seems to be best practice to return a 404 when a product or a listing – in a marketplace context – is no longer available. And from a UX perspective it's not good to return some custom response instead of a customized experience to users that helps them as much as possible to complete their job.
3. What do you mean with Astro.response doesn't exist? If I was to do the very same but calling Astro.response.status = 410 everything would work as expected and custom content is returned along a 410 status code.

[ematipico]

What's the reason that one cannot return a 404 with the content one wants?

404 is a special status code in Astro. Returning 404 will render the special route 404.astro or Astro default 404. That's why your special content should reside there, in 404.astro

2. Why does Astro have that restriction? In terms of SEO it seems to be best practice to return a 404 when a product or a listing – in a marketplace context – is no longer available. And from a UX perspective it's not good to return some custom response instead of a customized experience to users that helps them as much as possible to complete their job.

You can do that using 404.astro. There's no restriction in that route, as the others. You can access to Astro.locals, Astro.request, etc. and you can return the content that you want.

3. What do you mean with `Astro.response` doesn't exist? If I was to do the very same but calling `Astro.response.status = 410` everything would work as expected and custom content is returned along a 410 status code.

Sorry, I did not know that Astro.response is actually available. Apologies for that.

---

I would ask you to not reply to this issue anymore, if you don't mind. We use this issue tracker for bugs, and not support questions. If you still have questions, feel free to open a thread in the #support channel, on our Discord server.