How to Fix GraphQL Cannot Return Null for Non-Nullable Field Error
In this tutorial, you'll learn about How to Fix GraphQL Cannot Return Null for Non. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.
The Problem
Your GraphQL query returns:
{
"errors": [
{
"message": "Cannot return null for non-nullable field User.email.",
"locations": [{"line": 2, "column": 3}]
}
]
}
A resolver returned null for a field that is declared as non-nullable (using ! in the schema). GraphQL cannot return null and instead propagates the error upward.
Quick Fix
1. Check the resolver return value
The resolver may return undefined or null for a required field:
// Wrong — returns null for a non-nullable field
const resolvers = {
Query: {
user: async (_, { id }) => {
const user = await db.findUser(id)
return {
id: user.id,
name: user.name,
email: user.email || null // null is invalid for String!
}
}
}
}
// Right — provide a default or handle the missing value
const resolvers = {
Query: {
user: async (_, { id }) => {
const user = await db.findUser(id)
return {
id: user.id,
name: user.name,
email: user.email || '' // empty string instead of null
}
}
}
}
2. Change the field to nullable
If the field can legitimately be null, update the schema:
# Wrong — non-nullable field
type User {
id: ID!
name: String!
email: String! # throws error if null
}
# Right — nullable field
type User {
id: ID!
name: String!
email: String # can be null without error
}
3. Handle null propagation from child errors
If a child resolver throws, the parent non-nullable field becomes null:
// Wrong — child resolver error propagates
const resolvers = {
User: {
address: async (parent) => {
const addr = await db.findAddress(parent.id)
if (!addr) throw new Error('Address not found')
// This makes User.address null, and if it's non-nullable,
// the entire User becomes null
}
}
}
// Right — return null instead of throwing
const resolvers = {
User: {
address: async (parent) => {
const addr = await db.findAddress(parent.id)
return addr || null // return null instead of throwing
}
}
}
4. Check database query results
The database may return null for required fields:
// Wrong — assumes all fields are present
const resolvers = {
Query: {
user: async (_, { id }) => {
const [user] = await db.query(
'SELECT id, name, email FROM users WHERE id = ?',
[id]
)
return user // user.email may be NULL in DB
}
}
}
// Right — ensure non-null defaults
const resolvers = {
Query: {
user: async (_, { id }) => {
const [user] = await db.query(
'SELECT id, COALESCE(name, "") as name, COALESCE(email, "") as email FROM users WHERE id = ?',
[id]
)
return user
}
}
}
5. Use the @deprecated directive
If a field is being phased out, mark it deprecated instead of changing to nullable:
type User {
id: ID!
name: String!
email: String! @deprecated(reason: "Use emailAddress instead")
emailAddress: String # new nullable field
}
Prevention
- Use nullable fields for any value that may be missing.
- Always ensure resolvers return non-null values for fields marked with
!. - Test queries with partial data in development.
- Use data loaders to batch and handle missing data gracefully.
- Review schema changes carefully when adding non-null fields.
Common Mistakes with GraphQL null
- Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
- Using
headandtailinstead of pattern matching, causing runtime errors on empty lists - Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
These mistakes appear frequently in real-world API code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.
Practice Exercise
Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.
This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.
FAQ
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro