NextAuth CLIENT_FETCH_ERROR: the session call returned HTML
[next-auth][error][CLIENT_FETCH_ERROR]Short answer
The NextAuth client asks /api/auth/session for JSON and received an HTML page instead, usually a 404 or an error page. Either the [...nextauth] route does not exist at the path the client calls, or NEXTAUTH_URL points at the wrong address. Request the session URL directly to see which.
Fix it fast
1Find out which cause you have
Request the session endpoint yourself. A correct setup returns JSON, not an HTML page.
curl -i http://localhost:3000/api/auth/session2Match what you see, then jump to its fix
What does the error look like?
[next-auth][error][CLIENT_FETCH_ERROR]Unexpected token '<', "<!DOCTYPE "... is not valid JSON
Cause 1 of 2
The NextAuth route handler is missing or in the wrong folder
1Check
The catch-all route must be named [...nextauth] and sit under api/auth. With the Pages Router the file is pages/api/auth/[...nextauth].js.
find . -path ./node_modules -prune -o -name "*nextauth*" -print2Fix
Create the catch-all route in the right folder and export NextAuth with your options. With the App Router this is a Route Handler.
// pages/api/auth/[...nextauth].js
import NextAuth from 'next-auth'
import GithubProvider from 'next-auth/providers/github'
export const authOptions = {
providers: [
GithubProvider({
clientId: process.env.GITHUB_ID,
clientSecret: process.env.GITHUB_SECRET,
}),
],
}
export default NextAuth(authOptions)3Verify
The session URL now returns JSON.
curl -i http://localhost:3000/api/auth/sessionConfirmed by next-auth.js.org
Cause 2 of 2
NEXTAUTH_URL is wrong
1Check
The documentation lists a misconfigured NEXTAUTH_URL as a reason for this error. Compare it with the address you open in the browser.
grep -n "NEXTAUTH_URL" .env* 2>/dev/null2Fix
In production set NEXTAUTH_URL to the canonical URL of the site. If you use a custom base path, it must include the full route to the API endpoint.
# .env.production, or your host's env settings
NEXTAUTH_URL=https://example.com
# custom base path:
# NEXTAUTH_URL=https://example.com/custom-route/api/auth3Verify
Restart, reload the page, and check the session request returns JSON.
curl -i https://example.com/api/auth/sessionConfirmed by next-auth.js.org
How do I stop it coming back?
- Check /api/auth/session returns JSON after every deploy.
- Keep NEXTAUTH_URL per environment instead of copying one value everywhere.
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
NextAuth logs NO_SECRET, or throws it in production
In production, we expect you to define a secret property in your configuration
NextAuth needs a secret to encrypt its JWT and hash tokens.
2 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fix