Maaz Zindani

Loading the index…

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

NextAuth CLIENT_FETCH_ERROR: the session call returned HTML

Error[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.

  • Applies to next-auth 4, Next.js 15, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/session
  2. 2Match what you see, then jump to its fix

    1. 1curl shows 404 and an HTML page for /api/auth/sessionThe NextAuth route handler is missing or in the wrong folderFix
    2. 2The route exists, but the browser calls another host or path, for example a staging address, and gets an HTML pageNEXTAUTH_URL is wrongFix

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*" -print

2Fix

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/session

Confirmed by next-auth.js.org

Did this fix it?

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/null

2Fix

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/auth

3Verify

Restart, reload the page, and check the session request returns JSON.

curl -i https://example.com/api/auth/session

Confirmed by next-auth.js.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.