TypeScript rejects the authorize function of the Credentials provider
TypeScript error on the authorize callback of the Credentials providerShort 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.
Fix it fast
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 --noEmit2Match what you see, then jump to its fix
- 1
The error mentions undefined or a type that is not User | nullauthorize can return something other than a user or nullFix - 2
The compiler says an extra field you return does not exist on type UserThe returned user has fields the User type does not knowFix - 3
The 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
- 1
What does the error look like?
TypeScript error on the authorize callback of the Credentials providerA custom field you return from authorize is missing on the User or Session typeLogin 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/null2Fix
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 --noEmitConfirmed by authjs.dev
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 --noEmitConfirmed by authjs.dev
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.json2Fix
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 --noEmitConfirmed by next-auth.js.org
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
The user is undefined inside the NextAuth session callback
session.user.id is undefined
With JWT sessions, NextAuth gives the session callback a token, not a user.
3 causes, each with a fixWeb apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fixWeb apps
next build stops because of TypeScript errors
How to disable typescript for failing my builds with nextjs?
next build runs a TypeScript check and fails the build when it finds type errors.
2 causes, each with a fixWeb apps
TypeScript cannot resolve import './globals.css' in Next.js
ts(2882)
TypeScript now checks imports like import './globals.css' when noUncheckedSideEffectImports is on, and it finds no type for a CSS file.
2 causes, each with a fixWeb apps
getStaticProps is ignored or rejected in a Next.js project
How to fetch data server-side in the latest Next.js? Tried getStaticProps but it's not running and getting undefined
getStaticProps belongs to the Pages Router.
4 causes, each with a fixWeb apps
Type error after upgrading: params does not satisfy the PageProps constraint
Type '{ params: { id: string; }; }' does not satisfy the constraint 'PageProps'
Since Next.js 15, params and searchParams are Promises, not plain objects.
4 causes, each with a fix