Custom fetch server 404 responses are discarded

[nemvince]

Environment

• nitro@3.0.1-alpha.1
• vite@7.3.0

// vite.config.ts
import { nitro } from 'nitro/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [nitro()],
});

// nitro.config.ts
export default defineNitroConfig({
  serverDir: 'server',
});

Reproduction

StackBlitz

Describe the bug

When using Vite and a custom server.ts with fetch, if the fetch returns a 404 Response, it is discarded and the request is handled by the frontend

[coderabbitai]

🔗 Similar Issues

Related Issues

• [vite] server routes return handler file contents instead of proper response during vite dev #3553
• [v3] Using nitro/vite with cloudflare preset fails to start #3637
• /public/[filename].gz missing Content-Encoding: gzip Header #3379

🔗 Related PRs

#3817 - fix(vite): skip early dev handler for special prefixes [merged]

👤 Suggested Assignees

• alan-agius4
• franklin-tina
• OrbisK
• pi0

---

Enable issue planning

_{To enable issue planning, add the following to your .coderabbit.yaml:}

issue_enrichment:
  planning:
    enabled: true

_{You can then request a plan by commenting @coderabbitai plan on any issue.}

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[iiio2]

I think if we remove { status:404 } then the second route works also. I think { status: 404 } should be inside JSON.Stringify().

[nemvince]

sorry, but not being able to return an http response with status code 404 is definitely a completely unnecessary and arbitrary restriction, for example an oRPC not found error results in a 404 too

[pi0]

This issue should be fixed in latest nightly channel (alpha.2 soon)

You can try with:

"nitro": "npm:nitro-nightly@latest

[nemvince]

is there a config option to change? i installed nitro-nightly@latest but 404 responses are still being handled by my frontend

[pi0]

Sorry the docs are missing some information.

Currently, what happens is that when you have both server.ts and index.html, they both need to handle any route pattern (/**). Therefore server handler is registered as a middleware (falling back to index.html renderer if no match. if you remove index.html behavior changes as there is only one handler)

When using Web API format with export default { fetch } and returning a Response, there is no way to tell that a 404 response is actually a user 404 or a signal to call next middleware (SPA renderer).

Now if we assume a response with a 404 status is always an explicit signal to throw a 404 error, it breaks integration with web frameworks like hono and elysia as export default app returns a fetch handlers that returns a 404 Response either if it is a user 404 or there is no router match (to fallback to SPA). This is basically a limitation of Web APs being used as middleware.

---

For the solution, I strongly recommend using explicit routes (server/routes/api/upload.ts for example), it will be more efficient also for bundling and runtime performance.

You can also register server.ts for explicit patterns like below:

import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  serverDir: 'server',
  routes: {
    '/api/**': 'server.ts',
  }
});

Alternatively use h3 API for HTPResponse since it is a clear signal that it is a user reponse, it works.

import { defineHandler, HTTPResponse } from 'nitro/h3';

export default defineHandler(async (event) => {
  const path = event.url.pathname

  if (path == '/api/uploads/file1') {
    console.log('Returning file found for file1');
    return new HTTPResponse(
      JSON.stringify({
        message: 'file found',
      })
    );
  }

  if (path == '/api/uploads/file2') {
    console.log('Returning file not found for file2');
    // this is going to get ignored
    return new HTTPResponse(
      JSON.stringify({
        message: 'file not found',
      }),
      { status: 404 }
    );
  }
})