graphql-java · dondonz · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/src/main/java/graphql/ExceptionWhileDataFetching.java b/src/main/java/graphql/ExceptionWhileDataFetching.java
@@ -27,7 +27,7 @@ public class ExceptionWhileDataFetching implements GraphQLError {
     private final List<SourceLocation> locations;
     private final @Nullable Map<String, Object> extensions;
 
-    public ExceptionWhileDataFetching(ResultPath path, Throwable exception, SourceLocation sourceLocation) {
+    public ExceptionWhileDataFetching(ResultPath path, Throwable exception, @Nullable SourceLocation sourceLocation) {
         this.path = assertNotNull(path).toList();
         this.exception = assertNotNull(exception);
         this.locations = Collections.singletonList(sourceLocation);

diff --git a/src/main/java/graphql/GraphQL.java b/src/main/java/graphql/GraphQL.java
@@ -550,7 +550,7 @@ private CompletableFuture<ExecutionResult> parseValidateAndExecute(ExecutionInpu
                 return CompletableFuture.completedFuture(new ExecutionResultImpl(preparsedDocumentEntry.getErrors()));
             }
             try {
-                return execute(Assert.assertNotNull(executionInputRef.get()), preparsedDocumentEntry.getDocument(), graphQLSchema, instrumentationState, engineRunningState, profiler);
+                return execute(Assert.assertNotNull(executionInputRef.get()), assertNotNull(preparsedDocumentEntry.getDocument(), "document must not be null"), graphQLSchema, instrumentationState, engineRunningState, profiler);
             } catch (AbortExecutionException e) {
                 return CompletableFuture.completedFuture(e.toExecutionResult());
             }
@@ -565,14 +565,14 @@ private PreparsedDocumentEntry parseAndValidate(AtomicReference<ExecutionInput>
         if (parseResult.isFailure()) {
             return new PreparsedDocumentEntry(assertNotNull(parseResult.getSyntaxException(), "Parse result syntax exception cannot be null when failed").toInvalidSyntaxError());
         } else {
-            final Document document = parseResult.getDocument();
+            final Document document = assertNotNull(parseResult.getDocument(), "Document cannot be null when parse succeeded");
             // they may have changed the document and the variables via instrumentation so update the reference to it
             executionInput = executionInput.transform(builder -> builder.variables(parseResult.getVariables()));
             executionInputRef.set(executionInput);
 
             final List<ValidationError> errors;
             try {
-                errors = validate(executionInput, assertNotNull(document, "Document cannot be null when parse succeeded"), graphQLSchema, instrumentationState);
+                errors = validate(executionInput, document, graphQLSchema, instrumentationState);
             } catch (GoodFaithIntrospectionExceeded e) {
                 return new PreparsedDocumentEntry(document, List.of(e.toBadFaithError()));
             }

diff --git a/src/main/java/graphql/UnresolvedTypeError.java b/src/main/java/graphql/UnresolvedTypeError.java
@@ -32,8 +32,8 @@ private String mkMessage(ResultPath path, UnresolvedTypeException exception, Exe
         return format("Can't resolve '%s'. Abstract type '%s' must resolve to an Object type at runtime for field '%s.%s'. %s",
                 path,
                 exception.getInterfaceOrUnionType().getName(),
-                simplePrint(info.getParent().getUnwrappedNonNullType()),
-                info.getFieldDefinition().getName(),
+                simplePrint(assertNotNull(info.getParent(), "executionStepInfo parent must not be null").getUnwrappedNonNullType()),
+                assertNotNull(info.getFieldDefinition(), "fieldDefinition must not be null").getName(),
                 exception.getMessage());
     }
 

diff --git a/src/main/java/graphql/analysis/MaxQueryDepthInstrumentation.java b/src/main/java/graphql/analysis/MaxQueryDepthInstrumentation.java
@@ -9,6 +9,7 @@
 import graphql.execution.instrumentation.SimplePerformantInstrumentation;
 import graphql.execution.instrumentation.parameters.InstrumentationExecuteOperationParameters;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.function.Function;
 
@@ -84,7 +85,7 @@ QueryTraverser newQueryTraverser(ExecutionContext executionContext) {
                 .build();
     }
 
-    private int getPathLength(QueryVisitorFieldEnvironment path) {
+    private int getPathLength(@Nullable QueryVisitorFieldEnvironment path) {
         int length = 1;
         while (path != null) {
             path = path.getParentEnvironment();

diff --git a/src/main/java/graphql/analysis/QueryComplexityCalculator.java b/src/main/java/graphql/analysis/QueryComplexityCalculator.java
@@ -4,6 +4,9 @@
 import graphql.execution.CoercedVariables;
 import graphql.language.Document;
 import graphql.schema.GraphQLSchema;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -16,12 +19,13 @@
  * into it.
  */
 @PublicApi
+@NullMarked
 public class QueryComplexityCalculator {
 
     private final FieldComplexityCalculator fieldComplexityCalculator;
     private final GraphQLSchema schema;
     private final Document document;
-    private final String operationName;
+    private final @Nullable String operationName;
     private final CoercedVariables variables;
 
     public QueryComplexityCalculator(Builder builder) {
@@ -95,6 +99,7 @@ public static Builder newCalculator() {
         return new Builder();
     }
 
+    @NullUnmarked
     public static class Builder {
         private FieldComplexityCalculator fieldComplexityCalculator;
         private GraphQLSchema schema;

diff --git a/src/main/java/graphql/analysis/QueryComplexityInfo.java b/src/main/java/graphql/analysis/QueryComplexityInfo.java
@@ -3,17 +3,20 @@
 import graphql.PublicApi;
 import graphql.execution.instrumentation.parameters.InstrumentationExecuteOperationParameters;
 import graphql.execution.instrumentation.parameters.InstrumentationValidationParameters;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import org.jspecify.annotations.NullUnmarked;
 
 /**
  * The query complexity info.
  */
 @PublicApi
+@NullMarked
 public class QueryComplexityInfo {
 
     private final int complexity;
-    private final InstrumentationValidationParameters instrumentationValidationParameters;
-    private final InstrumentationExecuteOperationParameters instrumentationExecuteOperationParameters;
+    private final @Nullable InstrumentationValidationParameters instrumentationValidationParameters;
+    private final @Nullable InstrumentationExecuteOperationParameters instrumentationExecuteOperationParameters;
 
     private QueryComplexityInfo(Builder builder) {
         this.complexity = builder.complexity;
@@ -35,7 +38,7 @@ public int getComplexity() {
      *
      * @return the instrumentation validation parameters.
      */
-    public InstrumentationValidationParameters getInstrumentationValidationParameters() {
+    public @Nullable InstrumentationValidationParameters getInstrumentationValidationParameters() {
         return instrumentationValidationParameters;
     }
 
@@ -44,7 +47,7 @@ public InstrumentationValidationParameters getInstrumentationValidationParameter
      *
      * @return the instrumentation execute operation parameters.
      */
-    public InstrumentationExecuteOperationParameters getInstrumentationExecuteOperationParameters() {
+    public @Nullable InstrumentationExecuteOperationParameters getInstrumentationExecuteOperationParameters() {
         return instrumentationExecuteOperationParameters;
     }
 

diff --git a/src/main/java/graphql/analysis/QueryDepthInfo.java b/src/main/java/graphql/analysis/QueryDepthInfo.java
@@ -1,12 +1,14 @@
 package graphql.analysis;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.NullUnmarked;
 
 /**
  * The query depth info.
  */
 @PublicApi
+@NullMarked
 public class QueryDepthInfo {
 
     private final int depth;

diff --git a/src/main/java/graphql/analysis/QueryReducer.java b/src/main/java/graphql/analysis/QueryReducer.java
@@ -1,6 +1,7 @@
 package graphql.analysis;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Used by {@link QueryTraverser} to reduce the fields of a Document (or part of it) to a single value.
@@ -10,6 +11,7 @@
  * See {@link QueryTraverser#reducePostOrder(QueryReducer, Object)} and {@link QueryTraverser#reducePreOrder(QueryReducer, Object)}
  */
 @PublicApi
+@NullMarked
 @FunctionalInterface
 public interface QueryReducer<T> {
 

diff --git a/src/main/java/graphql/analysis/QueryTransformer.java b/src/main/java/graphql/analysis/QueryTransformer.java
@@ -13,6 +13,7 @@
 
 import java.util.LinkedHashMap;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.NullUnmarked;
 
 import static graphql.Assert.assertNotNull;
@@ -31,6 +32,7 @@
  * visitField calls.
  */
 @PublicApi
+@NullMarked
 public class QueryTransformer {
 
     private final Node root;

diff --git a/src/main/java/graphql/analysis/QueryTraversalOptions.java b/src/main/java/graphql/analysis/QueryTraversalOptions.java
@@ -1,11 +1,13 @@
 package graphql.analysis;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * This options object controls how {@link QueryTraverser} works
  */
 @PublicApi
+@NullMarked
 public class QueryTraversalOptions {
 
     private final boolean coerceFieldArguments;

diff --git a/src/main/java/graphql/analysis/QueryVisitor.java b/src/main/java/graphql/analysis/QueryVisitor.java
@@ -2,13 +2,15 @@
 
 import graphql.PublicApi;
 import graphql.util.TraversalControl;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Used by {@link QueryTraverser} to visit the nodes of a Query.
  * <p>
  * How this happens in detail (pre vs post-order for example) is defined by {@link QueryTraverser}.
  */
 @PublicApi
+@NullMarked
 public interface QueryVisitor {
 
     void visitField(QueryVisitorFieldEnvironment queryVisitorFieldEnvironment);

diff --git a/src/main/java/graphql/analysis/QueryVisitorFieldArgumentEnvironment.java b/src/main/java/graphql/analysis/QueryVisitorFieldArgumentEnvironment.java
@@ -7,10 +7,13 @@
 import graphql.schema.GraphQLFieldDefinition;
 import graphql.schema.GraphQLSchema;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Map;
 
 @PublicApi
+@NullMarked
 public interface QueryVisitorFieldArgumentEnvironment {
 
     GraphQLSchema getSchema();
@@ -21,7 +24,7 @@ public interface QueryVisitorFieldArgumentEnvironment {
 
     Argument getArgument();
 
-    Object getArgumentValue();
+    @Nullable Object getArgumentValue();
 
     Map<String, Object> getVariables();
 

diff --git a/src/main/java/graphql/analysis/QueryVisitorFieldArgumentInputValue.java b/src/main/java/graphql/analysis/QueryVisitorFieldArgumentInputValue.java
@@ -4,22 +4,25 @@
 import graphql.language.Value;
 import graphql.schema.GraphQLInputType;
 import graphql.schema.GraphQLInputValueDefinition;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * This describes the tree structure that forms from a argument input type,
  * especially with `input ComplexType { ....}` types that might in turn contain other complex
  * types and hence form a tree of values.
  */
 @PublicApi
+@NullMarked
 public interface QueryVisitorFieldArgumentInputValue {
 
-    QueryVisitorFieldArgumentInputValue getParent();
+    @Nullable QueryVisitorFieldArgumentInputValue getParent();
 
     GraphQLInputValueDefinition getInputValueDefinition();
 
     String getName();
 
     GraphQLInputType getInputType();
 
-    Value getValue();
+    @Nullable Value<?> getValue();
 }
diff --git a/src/main/java/graphql/analysis/QueryVisitorFieldArgumentValueEnvironment.java b/src/main/java/graphql/analysis/QueryVisitorFieldArgumentValueEnvironment.java
@@ -6,10 +6,12 @@
 import graphql.schema.GraphQLFieldDefinition;
 import graphql.schema.GraphQLSchema;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 
 import java.util.Map;
 
 @PublicApi
+@NullMarked
 public interface QueryVisitorFieldArgumentValueEnvironment {
 
     GraphQLSchema getSchema();

diff --git a/src/main/java/graphql/analysis/QueryVisitorFieldEnvironment.java b/src/main/java/graphql/analysis/QueryVisitorFieldEnvironment.java
@@ -9,10 +9,13 @@
 import graphql.schema.GraphQLOutputType;
 import graphql.schema.GraphQLSchema;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Map;
 
 @PublicApi
+@NullMarked
 public interface QueryVisitorFieldEnvironment {
 
     /**
@@ -46,11 +49,11 @@ public interface QueryVisitorFieldEnvironment {
      */
     GraphQLFieldsContainer getFieldsContainer();
 
-    QueryVisitorFieldEnvironment getParentEnvironment();
+    @Nullable QueryVisitorFieldEnvironment getParentEnvironment();
 
     Map<String, Object> getArguments();
 
-    SelectionSetContainer getSelectionSetContainer();
+    @Nullable SelectionSetContainer<?> getSelectionSetContainer();
 
     TraverserContext<Node> getTraverserContext();
 }
diff --git a/src/main/java/graphql/analysis/QueryVisitorFragmentDefinitionEnvironment.java b/src/main/java/graphql/analysis/QueryVisitorFragmentDefinitionEnvironment.java
@@ -5,8 +5,10 @@
 import graphql.language.Node;
 import graphql.schema.GraphQLSchema;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 
 @PublicApi
+@NullMarked
 public interface QueryVisitorFragmentDefinitionEnvironment {
 
     /**

diff --git a/src/main/java/graphql/analysis/QueryVisitorFragmentSpreadEnvironment.java b/src/main/java/graphql/analysis/QueryVisitorFragmentSpreadEnvironment.java
@@ -6,8 +6,10 @@
 import graphql.language.Node;
 import graphql.schema.GraphQLSchema;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 
 @PublicApi
+@NullMarked
 public interface QueryVisitorFragmentSpreadEnvironment {
 
     /**

diff --git a/src/main/java/graphql/analysis/QueryVisitorInlineFragmentEnvironment.java b/src/main/java/graphql/analysis/QueryVisitorInlineFragmentEnvironment.java
@@ -5,8 +5,10 @@
 import graphql.language.Node;
 import graphql.schema.GraphQLSchema;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 
 @PublicApi
+@NullMarked
 public interface QueryVisitorInlineFragmentEnvironment {
 
     /**

diff --git a/src/main/java/graphql/analysis/QueryVisitorStub.java b/src/main/java/graphql/analysis/QueryVisitorStub.java
@@ -1,8 +1,10 @@
 package graphql.analysis;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 @PublicApi
+@NullMarked
 public class QueryVisitorStub implements QueryVisitor {