Graphql cannot return null for non nullable field errors

You’re hitting the graphql cannot return null for non-nullable field error because your schema promised the client a value — and your resolver broke that promise. GraphQL treats this as a hard contract violation: a field marked String! or ID! must always return a real value, never null. When a resolver returns null for such a field, GraphQL doesn’t silently skip it — it nulls out the parent object, and that null can cascade all the way up to the root query, returning nothing at all.

This isn’t a bug in GraphQL — it’s the type system doing exactly what it was designed to do. But it does mean you need to know where the null is coming from and whether to fix the resolver or relax the schema. This guide walks you through both.

Understanding the Cannot Return Null for Non-Nullable Field Error

When GraphQL executes a query, it runs your resolvers and then validates every returned value against the schema. If a field is declared non-nullable with ! and its resolver returns null, the validation step immediately fails — but not just for that field. GraphQL propagates the null upward through the response tree until it hits a nullable field or the root. This means a single null in a deeply nested resolver can silently wipe out large chunks of your response.

Here’s what the actual error looks like in the response JSON:

{
  "data": {
    "user": null
  },
  "errors": [
    {
      "message": "Cannot return null for non-nullable field User.name",
      "locations": [{ "line": 3, "column": 5 }],
      "path": ["user", "name"],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ]
}

Notice that data.user is null — not just data.user.name. Because name was non-nullable, GraphQL couldn’t leave the User object in a partially-valid state, so it nulled the whole parent. If the query had fetched users: [User!]!, the entire list would be gone.

The Technical Explanation Behind the Error

The ! syntax in GraphQL schema definitions creates a non-nullable constraint enforced at execution time. When you write name: String!, you’re telling both clients and the server runtime: this field will always have a string value.

type User {
  id: ID!           # Non-nullable — always required
  name: String!     # Non-nullable — must have a value
  email: String     # Nullable — can be null
  profile: Profile  # Nullable — can be null
}

The GraphQL execution engine validates resolved values after all resolvers have run, before the response is sent. The validation is strict and implementation-agnostic — it works the same way in Apollo Server, graphql-java, Absinthe, and every other spec-compliant server. Your resolver code is responsible for ensuring it never returns null (or undefined in JavaScript) for a non-nullable field under any circumstances.

Common Scenarios That Trigger This Error

In practice, this error almost always comes from one of five places:

The most common pattern in async JavaScript resolvers is the silent undefined. An awaited function that throws but isn’t wrapped in try/catch will cause the resolver to return undefined, which GraphQL treats the same as null for non-nullable fields:

// ❌ Dangerous — if getUser throws, resolver returns undefined
const resolvers = {
  Query: {
    user: async (_, { id }) => {
      return await db.getUser(id); // throws if not found
    }
  }
};

// ✅ Safe — explicit handling
const resolvers = {
  Query: {
    user: async (_, { id }) => {
      const user = await db.getUser(id);
      if (!user) throw new GraphQLError(`User ${id} not found`, {
        extensions: { code: 'NOT_FOUND' }
      });
      return user;
    }
  }
};

The null propagation behavior is intentional in the spec — it prevents clients from receiving silently broken partial data. But it means your resolvers need to be explicit: either return a valid value, or throw a real error.

GraphQL Error Structure Analysis

Before you can fix the error, you need to read it correctly. The error response always contains a path array — this is your most important debugging tool.

Read the path array left to right — each element is a deeper level in your query. ["user", "profile", "name"] means: inside the user query → inside the profile field → the name field returned null. That immediately tells you to look at the resolver for Profile.name, not the root user resolver.

“message”: “Cannot return null for non-nullable field UpdateItemPayload.item.”
— Parse Platform Community
Source link

Diagnosing the Root Cause in Your Implementation

The fastest way to diagnose this error is to follow the path directly to the resolver. Here’s the workflow that works in production:

The critical step most developers skip is step 4 — running the query in isolation. Don’t assume the null comes from the resolver logic itself. Often it’s the database returning zero rows for a valid reason (deleted record, permission filter, etc.).

Examining Your Schema Definitions

After identifying the failing field, look at its schema definition. Ask one question: Is this field truly guaranteed to have a value in 100% of cases? If the honest answer is “mostly yes, but sometimes no,” it should be nullable.

A good rule of thumb from production experience: apply ! to IDs and system-generated values (timestamps, auto-increment keys) where the database guarantees non-null. Be more cautious with user-provided or relationship fields. You can always make a nullable field non-nullable later (additive, non-breaking) — but going the other direction requires a major version bump or migration.

Analyzing Your Resolver Functions

Resolvers are where null values are born. The most robust resolvers follow a simple pattern: fetch data, validate it exists, return it or throw.

For non-nullable fields specifically: never rely on optional chaining alone. user.profile?.name returns undefined when profile is missing — which still triggers the error. You need either a real fallback value or an explicit error throw.

Error handling patterns within resolvers have evolved through community experience. Rather than allowing null values to propagate silently, professional developers implement explicit error boundaries that either provide fallback values or throw informative errors that help clients understand why data isn’t available.

Framework-Specific Solutions

The GraphQL spec defines what must happen when a non-nullable field returns null. Each framework decides how to give you tools to prevent or transform that situation. Here’s what works in each major ecosystem.

Apollo Server Solutions

Apollo Server provides multiple layers of error handling. The formatError hook intercepts errors globally before they reach the client — useful for sanitizing messages in production:

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    if (formattedError.message.startsWith('Cannot return null')) {
      return {
        ...formattedError,
        message: 'Required data is temporarily unavailable',
        extensions: { code: 'DATA_UNAVAILABLE' }
      };
    }
    return formattedError;
  }
});

Client-side: setting errorPolicy: 'all' in Apollo Client lets your UI receive whatever data did resolve, alongside the error. Without this, Apollo Client defaults to returning null for the entire response when any error occurs — which is often worse than partial data.

Middleware Solutions for Absinthe (Elixir)

Absinthe’s middleware system lets you intercept and transform errors functionally, without touching individual resolvers. The Kronky library was built specifically for this:

defmodule MyApp.TranslateMessages do
  @behaviour Absinthe.Middleware

  def call(%{errors: errors} = resolution, _) do
    %{resolution | errors: Enum.map(errors, &translate_error/1)}
  end

  defp translate_error(%{message: "Cannot return null" <> _} = error) do
    %{error | message: "Required data is not available"}
  end
  defp translate_error(error), do: error
end

Absinthe’s integration with Phoenix also means you can handle these errors consistently across GraphQL and REST endpoints using Phoenix’s error view infrastructure — useful when you’re building a hybrid API.

TypeORM and type-graphql Integration Issues

The TypeORM + type-graphql stack has specific pitfalls around nullability. The most common: TypeORM entity decorators and type-graphql @Field decorators can disagree about what’s nullable, and TypeORM’s lazy loading doesn’t play well with GraphQL’s execution model.

@Entity()
@ObjectType()
class User {
  @PrimaryGeneratedColumn()
  @Field(() => ID)
  id: number;

  @Column({ nullable: true })
  @Field({ nullable: true })      // ← must match Column config
  name?: string;

  @OneToMany(() => Post, post => post.author)
  @Field(() => [Post], { nullable: true })
  posts?: Post[];                 // ← don't rely on lazy loading here
}

Solutions for Other GraphQL Implementations

Best Practices for Preventing This Error

The teams that rarely see this error in production share one habit: they treat nullability as a business contract decision, not a type-annotation habit. Before marking any field !, someone has to answer: “Can we guarantee this field will have a value for every record, past and future, including edge cases?”

Schema Design Principles

The GraphQL community has largely converged on a “nullable by default” approach for application-level types. The reasoning: it’s always a non-breaking change to add ! later (clients that handle null will still work), but removing ! is technically breaking (clients may stop doing null checks they no longer need). Starting nullable and tightening over time is safer than the reverse.

Union types are worth adopting for any field where “not found” is a legitimate, expected outcome. Instead of making user: User nullable, you can declare user: UserResult where UserResult = User | UserNotFound. This makes the “no data” case explicit and typed, which is better for both the schema contract and the client developer experience.

Implementing Robust Error Handling Patterns

A pre-deployment checklist for every non-nullable field:

Fallback strategies: for fields like display names or avatars, returning a computed default (“Anonymous”, a generic avatar URL) is often better than throwing an error. For fields like price or ID, throwing is correct — a product without a price is a data integrity problem that needs to surface. Match your strategy to the business meaning of the field.

Real-World Case Studies

Case Study: Fixing This Error in a Complex E-Commerce API

An e-commerce platform declared all inventory fields as non-nullable, based on the assumption that every product would always have stock data. During a major sales event, discontinued products started surfacing in search results — products that existed in the catalog but had been removed from the inventory system. Every query for these products failed with the null error, cascading to return null for entire product list pages.

The long-term fix was step 6 — creating explicit inventory records for discontinued products rather than leaving gaps. This let them restore the non-nullable constraint, which is always preferable to permanently loosening it. The schema became more correct, not less strict.

“The Project.client is marked as non-null, meaning that this field will always have a value. That means the User.project has to be null.”
— Advanced Web
Source link

Case Study: Resolving the Error in a Vulnerability Management System

A security platform required full audit trails for compliance: every vulnerability state transition had to have an author. The GraphQL schema declared author: User!. But automated security scans created state transitions without user accounts — no human initiated them.

The key insight: making author nullable would satisfy GraphQL but violate compliance requirements (the audit trail needed every transition attributed to someone or something). Creating a dedicated system user account preserved both the non-nullable constraint and the compliance rule. The resolver was updated to detect automation-initiated transitions and assign them to the system account, keeping the schema strict while handling the edge case correctly.