Maaz Zindani

Loading the index…

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

Swagger UI on Vercel loads blank and shows Unexpected token < in JSON

ErrorUnexpected token < in JSON at position 1

Short answer

The browser asked for a Swagger asset or spec and got an HTML page back, so it failed to parse it as JSON. On Vercel, express.static is ignored, so Swagger UI's files are not served. Serve them from public or a CDN, and make sure the spec file is in the function.

  • Applies to Express 4, Express 5, swagger-ui-express, Node.js 22, Vercel
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the browser's network tab on the docs page and look at which request returned HTML. Note its URL: a CSS or JS file, or the spec.

    curl -i https://your-app.vercel.app/api-docs/swagger-ui.css
    curl -i https://your-app.vercel.app/swagger.json
  2. 2Match what you see, then jump to its fix

    1. 1swagger-ui css or js requests return an HTML error pageExpress static serving is ignored on VercelFix
    2. 2The request for the spec file returns HTML or a 404 pageThe spec file is not part of the deployed functionFix

What does the error look like?

  • Unexpected token < in JSON at position 1

Cause 1 of 2

Express static serving is ignored on Vercel

1Check

Vercel's Express guide says express.static is ignored there and that static files belong in the public directory, served from its CDN. swagger-ui-express serves its UI files from the swagger-ui-dist package, so they depend on Express serving them.

grep -rn "swagger-ui-express\|express.static" --include=*.js --include=*.ts .

2Fix

Copy the UI css you need into public and point swagger-ui-express at its public URL with customCssUrl. The option takes a public URL, relative or absolute.

app.use(
  '/api-docs',
  swaggerUi.serve,
  swaggerUi.setup(spec, { customCssUrl: '/swagger-ui.css' })
);

3Verify

Redeploy and open the docs page. The stylesheet loads from the CDN.

curl -I https://your-app.vercel.app/swagger-ui.css

Confirmed by vercel.com

Did this fix it?

Cause 2 of 2

The spec file is not part of the deployed function

1Check

A spec read from disk at runtime must be in the function bundle. Vercel lets you add files with includeFiles in vercel.json.

ls swagger.json openapi.yaml 2>/dev/null

2Fix

Import the spec as a module so it is bundled, or add it with includeFiles.

{
  "functions": {
    "api/index.js": { "includeFiles": "swagger.json" }
  }
}

3Verify

Redeploy and request the spec URL. It returns JSON.

curl -s https://your-app.vercel.app/swagger.json | head -c 100

Confirmed by vercel.com

Did this fix it?

How do I stop it coming back?

  • Put every static file in public when you deploy Express to Vercel.
  • Keep the spec in code or in includeFiles, not read from an arbitrary path.
  • Open the docs page after each deploy.

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

The cors-anywhere.herokuapp.com demo proxy stopped working

Missing required request header. Must specify one of: origin,x-requested-with

The public cors-anywhere.herokuapp.com server is only a demo, is rate limited, and since February 2021 requires an opt-in.

2 causes, each with a fix

Web apps

CORS fails when you open an HTML file straight from disk

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///

A page opened from disk has an opaque origin, so browsers treat every request it makes as cross-origin, and CORS only works over http or https.

3 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.