Lorixen.
EN

"Unexpected token '<'... is not valid JSON": what it means

Short answer: The error "Unexpected token '<', "<!DOCTYPE "... is not valid JSON" means your JavaScript asked for JSON but received an HTML page. The < is the first character of <!DOCTYPE html>. Usually the request hit the wrong URL and got a 404 page, a login or error page, a single-page app's fallback index.html, or a firewall or maintenance page. Open the browser's Network tab, look at the failing request's status and response body, fix the URL or server route, and check response.ok and the content type before calling response.json().

What's actually happening

Browsers parse JSON with a strict parser. MDN's reference for JSON parsing errors explains that JSON.parse() throws a SyntaxError when a string fails to be parsed as JSON. response.json() in the Fetch API does the same thing to a response body. When that body is HTML, the parser stops at the very first character, <, and the browser reports it. Chrome's wording includes "Unexpected token '<'"; Firefox's wording is different, but the cause is the same.

The key point from MDN's guide to using Fetch: fetch() rejects its promise on network errors, but not when the server responds with an error status like 404. It fulfils with a Response, so code that calls .json() without checking the status will happily try to parse an HTML error page.

Step 1: Look at the real response

  1. Open developer tools and go to the Network tab.
  2. Reload and trigger the action that fails.
  3. Click the failing request and check:
    • Status: 404, 401, 403, 500, 502 or even 200
    • Response: what HTML came back. The page title often tells you everything: "Page not found", "Log in", "Just a moment...", "Maintenance".
    • Request URL: is it the address you intended?

Step 2: Match the cause

What you see Likely cause Fix
404 page Wrong URL: missing /api, typo, wrong base URL in production Correct the URL or environment variable
200 with your app's homepage Single-page app fallback serving index.html for unknown paths, including API paths Exclude API routes from the fallback, or fix the API path
Login page or redirect Session expired or request not sending cookies or token Handle 401 or redirect in code; include credentials
500 or 502 HTML page Server crashed or proxy couldn't reach the API Check server logs
"Checking your browser" page Bot protection or firewall challenging the API request Exempt the API path or adjust rules
Maintenance page Deploy or host maintenance mode Make the API return JSON errors during maintenance
Works locally, fails in production Relative URL resolving differently, or dev server proxy not present in production Set the production API base URL

The "works locally" case is very common: development servers often proxy /api to a backend, but the production build is served by a static host that knows nothing about that proxy and returns the app or a 404 instead.

Step 3: Make your code defensive

MDN's Fetch guide shows the standard pattern: check response.ok, which is true only for statuses in the 200 range, and throw an error otherwise before reading the body. Going a step further helps with debugging:

  1. Check the status. If !response.ok, throw an error that includes the status.
  2. Check the content type. If the Content-Type header doesn't include application/json, read the body as text and log the first few hundred characters.
  3. Show users a friendly message, not the raw error.

This turns a cryptic parser error into "API returned 404 text/html: <!DOCTYPE html><title>Page not found..." in your logs.

Step 4: Make your API return JSON errors

Ideally, every API route returns JSON even when things go wrong: {"error": "not_found"} with a 404 status, rather than the framework's default HTML error page. Check:

  • your framework's error handler for API routes
  • what your reverse proxy or host returns when the backend is down
  • authentication middleware, which often redirects to a login page instead of returning 401

Server-side code has the same issue

The same error appears in Node scripts, serverless functions and build tools that fetch data from APIs. The causes are identical: a changed endpoint, an expired API key returning a login page, or a supplier's maintenance page. Log the status and the first part of the body whenever parsing fails.

Catch it before customers do

Add monitoring that calls your key API endpoints regularly from outside and checks two things: the status code and that the response is valid JSON with the content type you expect. An uptime check that only looks for status 200 will miss the single-page app fallback case entirely, because that returns 200 with HTML. Also send front-end errors to an error-tracking tool, including the status and a short sample of the body, so a broken deploy shows up in minutes rather than when a customer emails. After each deploy, click through one or two actions that call the API.

An illustrative example

A hypothetical Galway bakery's ordering site worked on the developer's laptop, but in production the "check delivery slots" button failed with the "Unexpected token '<'" error. The Network tab showed the request to /api/slots returning status 200 with the site's own homepage HTML. The static host's single-page app rewrite was sending every unknown path, including /api/*, to index.html, because the API was on a separate server. The developer set the production API base URL to the API server's address and added a content-type check that logs non-JSON responses.

FAQ

Is my JSON file broken?

Probably not. If the response starts with <, you're not receiving your JSON at all.

Why does it happen only sometimes?

Intermittent causes include expiring sessions, bot challenges, rate limits or one unhealthy server behind a load balancer.

Can I just wrap it in try/catch?

You should handle errors, but find the cause too. A hidden failure becomes a silent bug.

What if the response starts with something other than <?

Look at the body. A PHP warning, a stray character or a byte-order mark before the JSON produces similar errors.

If an "Unexpected token" error is breaking your site or app and you'd like it traced, send us the page and what you clicked.

Sources

WhatsAppBook a call