Swagger UI on Vercel loads blank and shows Unexpected token < in JSON
Unexpected token < in JSON at position 1Short 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.
Fix it fast
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.json2Match what you see, then jump to its fix
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.cssConfirmed by vercel.com
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/null2Fix
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 100Confirmed by vercel.com
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
My Express server deployed to Vercel answers 404 on every route
The page works with node index.js but not on the .vercel.app URL
Vercel only finds an Express app when a file named app, index or server sits in a supported spot and exports the app or calls listen.
4 causes, each with a fixWeb apps
Axios sends no cookie to an Express API even with withCredentials set to true
The login response has a Set-Cookie header, but the browser stores nothing
withCredentials only tells the browser to attach cookies.
4 causes, each with a fixWeb 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 fixWeb apps
The browser rejects the CORS preflight because the OPTIONS reply is not a 2xx
The request in the Network tab is an OPTIONS call with a red status, and the real GET or POST never appears
Before some cross-origin calls the browser sends an OPTIONS preflight and treats any answer outside 200 to 299 as a network error.
3 causes, each with a fixWeb apps
A public website cannot reach your local dev server: local network request blocked
Look for and connect to any device on your local network
Chrome treats a request from a public website to localhost or a private IP as a local network request.
3 causes, each with a fixWeb 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