404 page fails to load with Node Standalone Adapter

[jelovac]

Astro Info

Astro                    v5.9.4
Node                     v22
System                   Linux (x64)
Package Manager          npm
Output                   static
Adapter                  @astrojs/node
Integrations             @astrojs/preact

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

Not browser specific.

Describe the Bug

I have an existing Astro site that has been in production, originally deployed as a static site served via Nginx inside a Docker container. This setup worked without issues, including proper rendering of the default 404 page when visiting unknown routes.

Recently, I needed to add a contact form, which required server-side processing. To support this, I switched the project to use the @astrojs/node adapter in standalone mode. Now, Astro is served via its built-in Node server, still running in Docker and behind nginxproxy/nginxproxy.

After this change:

• Home page and other valid routes load and work correctly
• astro dev and astro preview work locally with 404 behaving as expected.
• 404 page no longer renders in production when visiting non-existent routes. I don't get a response, the request is loading indefinitely.

In the docker container stdout logs I can see the following error at the moment when I try to access the page which is not present:

06:12:42 [@astrojs/node] Server listening on 
  local: http://localhost:4321 	
  network: http://XXX:4321

06:13:01 [ERROR] [@astrojs/node] Unhandled rejection while rendering undefined
TypeError: fetch failed
    at node:internal/deps/undici/undici:13510:13
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async #renderError (file:///app/server/chunks/_@astrojs-ssr-adapter_D6vczjnv.mjs:3374:29)
    at async file:///app/server/chunks/_@astrojs-ssr-adapter_D6vczjnv.mjs:3693:24 {
  [cause]: AggregateError [ECONNREFUSED]: 
      at internalConnectMultiple (node:net:1139:18)
      at internalConnectMultiple (node:net:1215:5)
      at afterConnectMultiple (node:net:1714:7) {
    code: 'ECONNREFUSED',
    [errors]: [ [Error], [Error] ]
  }
}
06:13:01 [ERROR] [@astrojs/node] Unhandled rejection while rendering undefined
TypeError: fetch failed
    at node:internal/deps/undici/undici:13510:13
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async #renderError (file:///app/server/chunks/_@astrojs-ssr-adapter_D6vczjnv.mjs:3374:29)
    at async file:///app/server/chunks/_@astrojs-ssr-adapter_D6vczjnv.mjs:3693:24 {
  [cause]: AggregateError [ECONNREFUSED]: 
      at internalConnectMultiple (node:net:1139:18)
      at internalConnectMultiple (node:net:1215:5)
      at afterConnectMultiple (node:net:1714:7) {
    code: 'ECONNREFUSED',
    [errors]: [ [Error], [Error] ]
  }
}

My astro.config.mjs

export default defineConfig({
  build: {
    assets: "assets/generated",
  },

  vite: {
    plugins: [tailwindcss()],
  },

  integrations: [preact()],

  adapter: node({
    mode: "standalone",
  }),
});

Important: I am using on demand rendering as described in the docs. In other words, I don't have output: "server" specified in my astro config. Instead I append export const prerender = false; to my server side APIRoute.

I was not able to reproduce the issue on StackBlitz as it runs in dev mode, which works fine on my end as well. Will try and create a new repo with the reproducible code.

What's the expected result?

The Node standalone server should properly render the 404 page on invalid routes, just like it does in local development and in the previous static deployment setup.

Link to Minimal Reproducible Example

N/A

Participation

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

[florian-lefebvre]

A github repo is fine as a minimal reproduction if you can't reproduce it on stackblitz!

[github-actions]

Hello @jelovac. Please provide a minimal reproduction using a GitHub repository or StackBlitz. Issues marked with needs repro will be closed if they have no activity within 3 days.

[jelovac]

Unfortunately, I haven’t been able to reproduce the issue locally. I did find a workaround by forcing the 404 page to be server-rendered using export const prerender = false;.

You may go ahead and close this issue, as I'm currently unable to spend more time trying to isolate and reproduce it in a test repository.

The most relevant discussion I’ve come across is this one:
https://community.fly.io/t/astro-5-7-2-custom-404-page-not-being-rendered-in-production/24791 (fyi not using fly.io)

For additional context:

The Docker images I built (which bundle Astro dist inside Node.js v22) target the ARM64 architecture and run inside rootless Podman containers. So far, I haven’t encountered any other issues with this setup as I am successfully running several more complex applications on this ARM-based VPS using Podman and various JavaScript stacks.

One thought that came up during troubleshooting is that the issue might be related to the nginxproxy setup. It is possible that Astro relies on something outside the standard configuration that needs to be explicitly enabled or forwarded by the proxy.

[florian-lefebvre]

Yeah I don't know this stuff enough to be of any help unfortunately. Even if you didn't manage to make a minimal repro, feel free to join our Discord and share your problem there: https://astro.build/chat/. I know some people in the community have this kind of setup so maybe they'll have ideas

[AlexStiyer]

I seem to have the same issue. Did you find a workaround @jelovac?

I've found that I can arrive at the 404 page if I explicitly go to the 404.html file.

Fixed by changing the output to 'server', but as "static" is the default behavior this either needs to be fixed or explicitly called out in the documentation.

[florian-lefebvre]

If you do find a solution, please send a docs PR!