Maaz Zindani

Loading the index…

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

TypeScript rejects the authorize function of the Credentials provider

ErrorTypeScript error on the authorize callback of the Credentials provider

Short answer

The authorize callback must return either a user object or null. Returning undefined, a database row of another shape, or throwing in the wrong place breaks the type. Return null on failure, and extend the User interface when your user has extra fields. Session and JWT types are extended with module augmentation.

  • Applies to next-auth 4, Auth.js 5, TypeScript 5, Next.js 15
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Let the compiler show the exact mismatch. The message names the property or return type that does not fit.

    npx tsc --noEmit
  2. 2Match what you see, then jump to its fix

    1. 1The error mentions undefined or a type that is not User | nullauthorize can return something other than a user or nullFix
    2. 2The compiler says an extra field you return does not exist on type UserThe returned user has fields the User type does not knowFix
    3. 3The compiler says the field does not exist on type Session even though a declaration file existsSession and JWT types were extended but are not picked upFix

What does the error look like?

  • TypeScript error on the authorize callback of the Credentials provider
  • A custom field you return from authorize is missing on the User or Session type
  • Login with wrong credentials ends on the page with ?error=CredentialsSignin

Cause 1 of 3

authorize can return something other than a user or null

1Check

The docs say the callback must return either a user object or null; null means the login failed. An early return with no value, or a lookup result that can be undefined, breaks that.

grep -n -A25 "authorize" auth.ts lib/auth.ts 2>/dev/null

2Fix

Validate the input, return null when the user or password is wrong, and return a plain user object otherwise.

async authorize(credentials) {
  if (!credentials?.email || !credentials?.password) return null
  const user = await getUserByEmail(credentials.email)
  if (!user) return null
  const ok = await verifyPassword(credentials.password, user.passwordHash)
  if (!ok) return null
  return { id: String(user.id), email: user.email, name: user.name }
}

3Verify

Run the type check again.

npx tsc --noEmit

Confirmed by authjs.dev

Did this fix it?

Cause 2 of 3

The returned user has fields the User type does not know

1Check

The docs say to augment the User interface so its type matches the response of your authorize callback. That keeps later callbacks such as jwt typed correctly.

ls types 2>/dev/null; grep -rn "declare module" --include=*.d.ts .

2Fix

Declare the extra fields on User in a .d.ts file.

// types/next-auth.d.ts
import 'next-auth'

declare module 'next-auth' {
  interface User {
    role?: string
  }
}

3Verify

Run the type check again.

npx tsc --noEmit

Confirmed by authjs.dev

Did this fix it?

Cause 3 of 3

Session and JWT types were extended but are not picked up

1Check

Session lives in next-auth and JWT lives in next-auth/jwt, so each needs its own declare module. The folder holding the file must be in typeRoots in tsconfig.json. Redeclaring a property overwrites the existing one, so add & DefaultSession['user'] to keep the defaults.

grep -n "typeRoots\|include" tsconfig.json

2Fix

Declare each module in the file and add the folder to typeRoots.

// types/next-auth.d.ts
import { DefaultSession } from 'next-auth'

declare module 'next-auth' {
  interface Session {
    user: { role?: string } & DefaultSession['user']
  }
}

declare module 'next-auth/jwt' {
  interface JWT {
    role?: string
  }
}

3Verify

Restart the TypeScript server in your editor and run the type check.

npx tsc --noEmit

Confirmed by next-auth.js.org

Did this fix it?

How do I stop it coming back?

  • Validate credentials on the server (for example with a schema library) before the database lookup.
  • Return only the fields you need from authorize, not the whole database row with the password hash.
  • Keep all next-auth type extensions in one types file.

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.