GTMRun

Soft 404s: return a real 404

Last updated: 2026-11-16

Google recommendation

What it is #

A soft 404 is a page that tells people "not found" (or shows your homepage) but returns HTTP 200 OK to crawlers. It usually comes from single-page apps whose hosting sends every unknown URL to index.html so the client-side router can take over.

Why it matters #

Google recommends meaningful HTTP status codes and calls out soft 404s in single-page apps specifically. When every made-up URL returns 200, Google has to guess which pages are real. Typos, old links and junk URLs can end up crawled as duplicates of your homepage, and a checker (ours included) can't tell which pages you actually have.

How we check it #

We request a path that can't exist, /gtmrun-soft404-check-7f3a9c, and fail this check if the response is 200. This check is informational and worth 0 points.

When your site does this, we also can't tell whether /pricing or /blog really exist, so those checks show not measured instead of passing. Fixing soft 404s turns them back into real checks.

How to fix #

The goal: known routes return 200, everything else returns 404 (ideally with a friendly "not found" page).

CloudFront + S3 (SPA)
The common setup maps 403/404 errors → /index.html with response code 200.
That's the soft-404. Options, simplest first:
1. Pre-render your public routes to real files (/pricing/index.html, etc.)
   and map errors to a real /404.html with response code 404.
2. Keep the SPA fallback only for app routes: a CloudFront Function that
   rewrites /dashboard/* to /index.html, with no global error mapping.
Vercel
Framework builds (Next.js, SvelteKit, Astro) return real 404s by default.
If you added a catch-all rewrite ("source": "/(.*)" → "/index.html"),
narrow it to your app's routes, and add a 404 page (e.g. app/not-found.tsx).
Netlify
A `/* /index.html 200` rule in _redirects is the soft-404.
Narrow it (e.g. `/app/* /index.html 200`) and add a 404.html at the root.
React Router / Vue Router
If the host must serve index.html for everything, at least tell Google:
in your catch-all "not found" route, add <meta name="robots" content="noindex">
(Google's JavaScript SEO guide documents this pattern).

Verify it yourself #

curl -s -o /dev/null -w '%{http_code}\n' https://yourdomain.com/this-page-does-not-exist

You want 404.

Runs GTMRun's own checks only — seconds, no third-party calls.

Tips #

  • Don't redirect missing pages to your homepage. Google treats that as a soft 404 too. A clear 404 page with a link home is better for people and crawlers.
  • The SPA fallback is a hosting setting, not a code bug. It usually lives in your CDN or host config, not in your React code.
  • What we learned: the legacy gtmrun.co app answered 200 for any path because of the global CloudFront error mapping in front of its React shell, so our own check could not tell whether /pricing existed. This site is static HTML with a real 404.html and no fallback — try any made-up address on it.

Sources #