Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

The Vite dev proxy does not forward my /api requests

ErrorGET http://localhost:5173/api/users 404 (Not Found)

Short answer

Vite proxies only requests whose path starts with a key in server.proxy, and it forwards the full path unless you rewrite it. Check that the browser calls a relative URL like /api/users, that the backend really has the /api prefix, and remember the proxy exists only in the dev and preview servers.

  • Applies to Vite 7, Node.js 22, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the Network tab and look at the full URL of one failing call. A call to localhost:5173/api/... means the proxy matched; a call to another host means the code bypasses it.

    grep -rn "localhost:\|fetch(\|axios" src/ | head -20
  2. 2Match what you see, then jump to its fix

    1. 1The Network tab shows an absolute URL to the backend, or a path whose start differs from the keyThe request path does not start with a proxy key, or the call uses a full URLFix
    2. 2The proxy works (the backend answers) but replies 404 for /api/usersThe backend has no /api prefix, so the forwarded path returns 404Fix
    3. 3The remote or virtual-host backend answers with another site's page or a 404 although the path is rightThe backend picks its site by the Host headerFix
    4. 4The proxy fails to reach an https target that works with certificate checks offThe target is https with a self-signed certificateFix
    5. 5Everything works with npm run dev, and /api returns 404 or HTML after deployingThe built site is served somewhere the proxy does not existFix

What does the error look like?

  • GET http://localhost:5173/api/users 404 (Not Found)
  • The browser calls the backend directly instead of going through the Vite dev server

Cause 1 of 5

The request path does not start with a proxy key, or the call uses a full URL

1Check

Vite proxies a request only when its path starts with a key in server.proxy. A call written as http://localhost:5000/api/x never reaches the Vite server.

grep -n "proxy" -A8 vite.config.*

2Fix

Call a relative path that starts with the key. If your config sets a non-relative base, put that base in front of each key.

// vite.config.js
export default defineConfig({
  server: { proxy: { '/api': 'http://localhost:5000' } },
})

// client code
fetch('/api/users')

3Verify

Restart the dev server, since config changes need it, and repeat the call.

curl -i http://localhost:5173/api/users

Confirmed by vite.dev

Did this fix it?

Cause 2 of 5

The backend has no /api prefix, so the forwarded path returns 404

1Check

The proxy sends the path on unchanged. Ask the backend directly for both forms.

curl -i http://localhost:5000/users
curl -i http://localhost:5000/api/users

2Fix

Strip the prefix with rewrite, and set changeOrigin as the documented example does.

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:5000',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
}

3Verify

The call through Vite now returns what the backend returns directly.

curl -i http://localhost:5173/api/users

Confirmed by vite.dev

Did this fix it?

Cause 3 of 5

The backend picks its site by the Host header

1Check

By default the Host header keeps the dev server's value. With changeOrigin the proxy changes the host header to the target URL.

curl -i -H "Host: localhost:5173" https://api.example.com/users

2Fix

Turn on changeOrigin for that proxy entry.

server: {
  proxy: {
    '/api': { target: 'https://api.example.com', changeOrigin: true },
  },
}

3Verify

Repeat the request through the dev server.

curl -i http://localhost:5173/api/users

Confirmed by github.com

Did this fix it?

Cause 4 of 5

The target is https with a self-signed certificate

1Check

The proxy option secure controls whether the target's SSL certificate is verified.

curl -I https://my-local-api.test/

2Fix

Set secure to false for that entry in development only.

server: {
  proxy: {
    '/api': { target: 'https://my-local-api.test', secure: false },
  },
}

3Verify

Call the path through the dev server.

curl -i http://localhost:5173/api/users

Confirmed by github.com

Did this fix it?

Cause 5 of 5

The built site is served somewhere the proxy does not exist

1Check

server.proxy configures the dev server, and the preview server inherits it by default. A static host serving dist/ has no proxy at all.

npm run build && npx vite preview

2Fix

In production, point the app at the real API URL (for example through a VITE_ variable) or set up a reverse proxy on the host that serves dist/.

# .env.production
VITE_API_URL=https://api.example.com

// client code
fetch(`${import.meta.env.VITE_API_URL}/users`)

3Verify

Build and check the deployed network call goes to the API host.

npm run build

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Use relative paths (/api/...) in client code and keep the backend host only in vite.config.
  • Restart the dev server after editing vite.config.
  • Decide early how production reaches the API, since the dev proxy will not exist there.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.