HTTP 404 Not Found — What It Means and How to Fix It

What causes this error

HTTP 404 means the server has no handler or resource mapped to the requested URL. Common causes: URL typo or version mismatch (`/v1/` vs `/v2/`), resource genuinely deleted or moved, trailing slash mismatch, SPA routes returning 404 on hard refresh because the server doesn't know about client-side routes, case-sensitive paths on Linux servers, and API versioning migration that left old endpoints without redirects.

How to fix it

1. 01

   step 1

   Double-check the exact URL including version, trailing slash, and case

   Linux web servers are case-sensitive. `/Users/123` and `/users/123` are different paths. Also check for a trailing slash difference — `/api/users` vs `/api/users/` behaves differently depending on server config. Get the precise URL from your API docs.

   # Test with and without trailing slash
   curl -si https://api.example.com/users -o /dev/null -w '%{http_code}\n'
   curl -si https://api.example.com/users/ -o /dev/null -w '%{http_code}\n'
   
   # Follow redirects to see where you end up
   curl -siL https://api.example.com/users

   Copy
2. 02

   step 2

   For SPAs: configure the server to return index.html for all routes

   React, Vue, and Angular apps handle routing client-side. When a user navigates to `/dashboard/settings` directly, the server gets a request for that path and returns 404 because there's no file there. The fix: configure the server to return `index.html` for all non-file paths.

   # Nginx — serve index.html for all SPA routes
   location / {
       try_files $uri $uri/ /index.html;
   }
   
   # Vercel — vercel.json
   {
     "rewrites": [{"source": "/(.*)", "destination": "/index.html"}]
   }

   Copy
3. 03

   step 3

   For Next.js/Express: verify the route handler exists

   Print all registered routes to confirm the route exists on the server side. In Express, use `express-list-routes`. In Next.js, check the `app/` or `pages/` directory structure.

   // Express: list all routes at startup
   const listRoutes = require('express-list-routes')
   listRoutes(app)  // prints all registered routes
   
   // Or manually inspect router stack
   app._router.stack.forEach(r => {
     if (r.route) console.log(r.route.path)
   })

   Copy
4. 04

   step 4

   Check if the resource was moved — add redirects

   If a URL changed due to a refactor or API versioning, add 301 (permanent) or 302 (temporary) redirects from the old path to the new one. Never leave old URLs returning 404 — it breaks clients and loses SEO equity.

   // Express: add a redirect from old to new path
   app.get('/api/v1/users/:id', (req, res) => {
     res.redirect(301, `/api/v2/users/${req.params.id}`)
   })

   Copy
5. 05

   step 5

   Distinguish intentional 404 from security-motivated 404

   Some APIs return 404 instead of 403 when a resource exists but the requester can't access it (to avoid disclosing resource existence). If you suspect this, try authenticating and check if the response code changes. AWS S3 and Stripe both use this pattern.

   # Test without auth vs with auth — if 404 becomes 403 or 200, it's an access issue
   curl -si https://api.example.com/resource/123
   curl -si https://api.example.com/resource/123 \
     -H 'Authorization: Bearer token'

   Copy

How to verify the fix

• The URL returns a 2xx response.
• Old URLs that were moved return a 301 redirect to the new location.
• SPA routes work on hard refresh (not just initial navigation).