TypeScript does not know the custom fields you add to the NextAuth user
Property 'role' does not exist on type 'User | AdapterUser'.Short answer
NextAuth ships fixed types for User, Session and JWT, so a field like role is unknown to TypeScript until you declare it. Add a declaration file that augments next-auth and next-auth/jwt, make sure tsconfig includes that file, and keep the default user fields by spreading DefaultSession['user'].
Fix it fast
1Find out which cause you have
Find out whether the project already has an augmentation file, and where it lives.
grep -rn --include=*.d.ts "declare module \"next-auth" . --exclude-dir=node_modules2Match what you see, then jump to its fix
- 1
The grep finds nothing, and the error names User or Session.The types were never augmentedFix - 2
The file exists but tsc still reports the error.The declaration file is not part of the TypeScript projectFix - 3
role now works, but session.user.name or session.user.image is a type error.The augmentation replaced the default user fieldsFix
- 1
What does the error look like?
Property 'role' does not exist on type 'User | AdapterUser'.
Cause 1 of 3
The types were never augmented
1Check
The built-in User interface has no role field, so reading user.role in a callback fails. The same holds for Session and for the JWT token.
grep -rn "token.role\|user.role\|session.user.role" app src pages 2>/dev/null2Fix
Create types/next-auth.d.ts and declare the extra field on User, Session and JWT. The JWT interface lives in the next-auth/jwt module, so it gets its own declare block.
// types/next-auth.d.ts
import { DefaultSession } from "next-auth"
declare module "next-auth" {
interface User {
role?: string
}
interface Session {
user: {
role?: string
} & DefaultSession["user"]
}
}
declare module "next-auth/jwt" {
interface JWT {
role?: string
}
}3Verify
Run the type checker; the error is gone.
npx tsc --noEmitConfirmed by next-auth.js.org
Cause 2 of 3
The declaration file is not part of the TypeScript project
1Check
A module declaration only takes effect when the file is included in tsconfig.json. The v4 docs say the types folder must be listed in typeRoots; the Auth.js docs say the file must be included in the project.
grep -n -E "typeRoots|include" tsconfig.json2Fix
Add the folder to typeRoots, or make sure the file matches an include pattern.
{
"compilerOptions": {
"typeRoots": ["./node_modules/@types", "./types"]
},
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "types/**/*.d.ts"]
}3Verify
Restart the TypeScript server in your editor and run tsc again.
npx tsc --noEmitConfirmed by authjs.dev
Cause 3 of 3
The augmentation replaced the default user fields
1Check
TypeScript merges new interface properties and overwrites existing ones, so redeclaring user inside Session drops name, email and image.
grep -n "interface Session" -A 4 types/next-auth.d.ts2Fix
Intersect your fields with DefaultSession['user'], as in the first example.
interface Session {
user: { role?: string } & DefaultSession["user"]
}3Verify
Type-check again.
npx tsc --noEmitConfirmed by authjs.dev
How do I stop it coming back?
- Declare every custom field once in types/next-auth.d.ts, and copy it in the jwt and session callbacks.
- Run tsc --noEmit in CI so a missing declaration fails the pull request.
- Make custom fields optional unless every sign-in path sets them.
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 fixBack end
create-next-app keeps creating a TypeScript project
Would you like to use TypeScript? No / Yes
create-next-app now makes a TypeScript project by default.
2 causes, each with a fixBack end
TypeScript cannot find '@angular/platform-browser' in an Angular project
Cannot find module '@angular/platform-browser' or its corresponding type declarations.
TS2307 means TypeScript could not turn the import into a file.
3 causes, each with a fixBack end
Angular build fails with TS2707 or "has no exported member" after installing a library
Module '"@angular/core"' has no exported member
These errors mean a library was compiled by a newer Angular than your app uses.
3 causes, each with a fixBack end
cdk synth says --app is required
--app is required either in command-line, in cdk.json or in ~/.cdk.json
The CDK CLI needs a command that runs your app and finds it in three places: the --app option, cdk.json in the project folder, or cdk.json in your home folder.
3 causes, each with a fixBack end
TypeScript cannot find module '@nestjs/core' or its type declarations
error TS2307: Cannot find module '@nestjs/common' or its corresponding type declarations.
TS2307 means TypeScript searched node_modules and found neither the package nor its types.
3 causes, each with a fix