What this usually means
The core issue is almost always a mismatch between where the authentication middleware puts the user object and where the resolver expects it. GraphQL resolvers receive a `context` object that must be populated before any resolver runs. If the middleware decorates `req.user` but the context function reads `req.auth`, or if middleware runs after context creation, the resolver sees `undefined`. Another common cause is the resolver field name not matching the schema definition (e.g., schema defines `me: User` but resolver exports `Me`). Because GraphQL swallows many errors by default, especially in production, the resolver can fail to execute without a clear error message.
The first ten minutes — establish facts before touching code.
- 1Add a logging middleware right before the GraphQL handler: `app.use('/graphql', (req, res, next) => { console.log('Context before:', JSON.stringify(req.user)); next(); })`
- 2In your context function, log the raw request object keys: `console.log('Request keys:', Object.keys(req))`
- 3Check if the resolver function is actually exported with the correct name matching the schema: `console.log(module.exports)` vs schema field name
- 4Temporarily hardcode `context.user = { id: 1 }` to see if the resolver works at all
- 5Use Apollo Studio or GraphiQL with `Include 'extensions'` to see if any underlying error is hidden
The specific files, logs, configs, and dashboards that usually own this bug.
- searchGraphQL context function (e.g., `apollo-server` context or `express-graphql` rootValue)
- searchAuthentication middleware (Passport, JWT verify, session) – check its placement relative to the GraphQL handler
- searchResolver file – verify export name matches schema field name exactly (case-sensitive)
- searchGraphQL schema – check that the field type returns a non-nullable object (e.g., `me: User!`)
- searchServer logs – look for 'Authentication failed' or 'Token expired' warnings that may be caught upstream
- searchNetwork tab – inspect the exact response body for hidden errors in `extensions`
Practical causes, not theory. These are the things you will actually find.
- warningAuthentication middleware runs AFTER the GraphQL middleware (order matters)
- warningContext function reads `req.user` but middleware sets `req.userData` or `req.auth`
- warningResolver function name typo: schema says `getUser` but export is `getuser` or `get_user`
- warningApollo Server `context` is an async function that throws, causing context to be empty
- warningGraphQL schema defines the field but resolver is attached to a different type (e.g., `Query.me` vs `User.me`)
- warningToken verification silently fails (expired, malformed) and middleware doesn't set any user – resolver gets undefined
Concrete fix directions. Pick the one that matches your root cause.
- buildEnsure middleware order: authentication before GraphQL handler: `app.use(authMiddleware); app.use('/graphql', graphqlHandler)`
- buildStandardize context key: always use `req.user` from middleware, then in context: `{ user: req.user }`
- buildUse Apollo Server's `context` as an async function with try-catch to provide a fallback: `context: async ({ req }) => { try { return { user: await getUser(req) }; } catch { return { user: null }; } }`
- buildExplicitly check for null user in resolver and return an error: `if (!context.user) throw new AuthenticationError('Not authenticated')`
- buildUse GraphQL schema directives like `@auth` or `@requiresAuth` to enforce authentication declaratively
A fix you cannot prove is a guess. Close the loop.
- verifiedAdd a test query `{ __typename }` after fixing – should return `{ "data": { "__typename": "Query" } }`
- verifiedCall the authenticated field with a valid token and inspect the response – should return data, not null
- verifiedRemove the token and call the field – should return a clear authentication error, not null data
- verifiedCheck server logs for the middleware logging line confirming user object is present
- verifiedWrite an integration test that sends a request with an invalid token and asserts a 401 or error response
Things that make this bug worse or harder to find.
- warningDo not rely on GraphQL's default error masking – it hides resolver failures in production; enable `debug: false` and catch errors explicitly
- warningDo not confuse `context` with `rootValue` in express-graphql – they are different parameters
- warningDo not set `context` to just `req` – it pollutes resolvers with the entire request object and may cause security issues
- warningDo not assume the resolver runs if the field is nullable – GraphQL can return `null` without error if the resolver returns undefined
- warningDo not skip checking the actual HTTP response status – GraphQL over HTTP often returns 200 even when there's an error in the response body
The Silent Null Return – GraphQL Authentication Resolver Not Executing
Timeline
- 09:15Deploy new feature: add `me` query to GraphQL schema that returns current user
- 09:45QA reports that `me` query returns `null` for authenticated users
- 10:00Check server logs – no errors, middleware seems to run (logs 'Authenticated user: 123')
- 10:15Add console.log in resolver – it never prints; resolver not executing
- 10:30Inspect Apollo Server context function – sees `req.user` is present but resolver still null
- 10:45Compare schema field name `me` with resolver export: schema has `me: User` but resolver file exports `me: () => {}` – correct
- 11:00Notice in GraphQL schema that `me` field is defined on `Query` type, but resolver file is attached to `User` type resolver map instead of `Query`
- 11:05Fix: move `me` resolver from `User` resolver map to `Query` resolver map
- 11:10Test query returns user object correctly; deploy fix
I had just merged a new feature adding a `me` query to our GraphQL API. The schema change was straightforward: add a `me: User` field to the `Query` type. I wrote the resolver, wired it into Apollo Server's resolver map, and deployed. QA immediately flagged that the `me` query returned `null` for any authenticated user. The weird part: no error in the response, no stack trace, no 4xx status. Just `{ "data": { "me": null } }`.
I started by verifying authentication middleware. Passport's JWT strategy was logging 'Authenticated user: 123' every request. The context function also logged `req.user` – it was there. But the resolver never ran. I added a `console.log('me resolver called')` – nothing. I thought maybe the resolver wasn't being called due to a type mismatch. I double-checked the resolver export name: `me: () => { ... }` – matched the schema. I even hardcoded a return – still null.
After an hour of frustration, I looked at the resolver map structure. We had separate files for Query resolvers and User resolvers. I had accidentally placed the `me` resolver inside the `User` resolvers object rather than the `Query` resolvers object. Apollo Server expected `Query.me`, not `User.me`. Since `User` doesn't have a `me` field in the schema, the resolver was simply ignored. Moving it to the correct map fixed it instantly. The lesson: always verify the resolver map structure matches the schema types exactly.
Root cause
Resolver function placed under wrong type in resolver map (User instead of Query), causing Apollo Server to silently ignore it.
The fix
Moved `me` resolver from `User` resolvers object to `Query` resolvers object in the resolver map passed to Apollo Server.
The lesson
GraphQL resolvers are matched by type and field name. A resolver under the wrong type is silently ignored. Always print the full resolver map structure and cross-reference with schema types.
GraphQL resolvers are functions that resolve a value for a field in the schema. The execution engine starts at the root Query type and walks the selection set. For each field, it looks up the resolver by type name and field name in the resolver map. If the resolver is not found, it uses a default resolver that simply looks at the parent object's property with the same name.
The critical point: if a resolver is placed under the wrong type (e.g., `User.me` instead of `Query.me`), or if the field name has a typo, the engine silently falls back to the default resolver. If the parent object doesn't have that property, it returns `null`. No error is thrown. This is the most common and insidious cause of 'resolver not firing' bugs.
Another common pattern is the middleware that sets the user runs after the GraphQL handler is registered. In Express, middleware order is everything. If you call `app.use(graphqlHandler)` before `app.use(authMiddleware)`, the GraphQL handler will fire first and the auth middleware will never run for that route.
Even if the order is correct, the context function must explicitly read from the right property. If your JWT middleware sets `req.userData` but your context function reads `req.user`, the resolver gets `undefined`. Always log `Object.keys(req)` in the context function to see what's actually available.
By default, Apollo Server 4 masks errors in production to avoid leaking implementation details. This means if your resolver throws an error, the client sees `null` and a generic error message. To see the real error, either enable `includeStacktraceInErrorResponses: true` in production (not recommended) or use `formatError` to log full errors server-side.
Similarly, express-graphql's `graphqlHTTP` accepts a `customFormatErrorFn` option. Without it, errors are serialized with only `message` and `locations`. Always log the original error in your context or resolver to avoid debugging blind.
If your context function is async (common for fetching user from DB), ensure it properly returns the object. An unhandled promise rejection in the context function can cause Apollo Server to use an empty context. Wrap your context function in try-catch and log any errors.
Additionally, if you use `express-graphql`'s `rootValue` instead of `context`, remember that `rootValue` is passed as the root value to every resolver, not per-request context. For per-request data like the authenticated user, you must use `context`.
Frequently asked questions
Why does my resolver return null but no error?
This usually means the resolver is not being called at all. GraphQL defaults to looking for a property on the parent object if no resolver is found. Check that your resolver is in the correct type map and that the field name matches exactly. Also verify that the field is not nullable in the schema – if it's marked with `!` you'll get an error instead of null.
How do I verify that my authentication middleware runs before the GraphQL handler?
Add a console.log inside the middleware and another inside the context function. If the middleware log appears after the context log, the order is wrong. In Express, ensure `app.use(authMiddleware)` is called before `app.use('/graphql', graphqlHandler)`. You can also use a debugging proxy like `morgan` to see the request flow.
My context.user is undefined in the resolver but req.user is set – why?
The context function likely reads from the wrong property. Check your context function: if it's `context: ({ req }) => ({ user: req.user })`, but your middleware sets `req.userData`, then `req.user` is undefined. Log `Object.keys(req)` in the context function to see all available properties. Also ensure the context function is not async and failing silently.
Can I use GraphQL directives to enforce authentication instead of checking in every resolver?
Yes, you can use schema directives like `@auth` (custom) or libraries like `graphql-shield` to apply authentication rules declaratively. These directives run before the resolver, so you don't need to manually check `context.user` in each resolver. However, they rely on the same context object, so middleware ordering and property naming are still critical.
Why does my REST endpoint work with auth but GraphQL doesn't?
Likely because the REST route uses a different middleware chain. GraphQL often sits on a single endpoint (`/graphql`) where you must explicitly add the auth middleware. Also, GraphQL's context function may not be reading the request object correctly. Check that the middleware is applied to the GraphQL route specifically, and that the context function accesses `req` from the first argument (Apollo Server) or `request` (express-graphql).