What causes "Null check failed on return value of %s" in google/guava?

Read the cause to find the failing method and parameter; add a null check (checkNotNull/requireNonNull) or annotate the parameter @Nullable if null is intentionally accepted.

google/guava · error · AssertionError

Null check failed on return value of %s

Error message

Null check failed on return value of %s

What it means

Thrown by ClassSanityTester.FactoryMethodReturnValueTester.testNulls() when nullPointerTester.testAllPublicInstanceMethods(instance) fails on an object returned by a static factory. The wrapping AssertionError records which factory produced the bad instance; the cause (AssertionError) describes which method failed the null-check.

Source

Thrown at android/guava-testlib/src/com/google/common/testing/ClassSanityTester.java:468

    /**
     * Tests null checks against the instance methods of the return values, if any.
     *
     * <p>Test fails if default value cannot be determined for a constructor or factory method
     * parameter, or if the constructor or factory method throws exception.
     *
     * @return this tester
     */
    @CanIgnoreReturnValue
    public FactoryMethodReturnValueTester testNulls() throws Exception {
      for (Invokable<?, ?> factory : getFactoriesToTest()) {
        Object instance = instantiate(factory);
        if (instance != null
            && packagesToTest.contains(Reflection.getPackageName(instance.getClass()))) {
          try {
            nullPointerTester.testAllPublicInstanceMethods(instance);
          } catch (AssertionError e) {
            throw new AssertionError("Null check failed on return value of " + factory, e);
          }
        }
      }
      return this;
    }

    /**
     * Tests {@link Object#equals} and {@link Object#hashCode} against the return values of the
     * static methods, by asserting that when equal parameters are passed to the same static method,
     * the return value should also be equal; and vice versa.
     *
     * <p>Test fails if default value cannot be determined for a constructor or factory method
     * parameter, or if the constructor or factory method throws exception.
     *
     * @return this tester
     */
    @CanIgnoreReturnValue
    public FactoryMethodReturnValueTester testEquals() throws Exception {

View on GitHub (pinned to 94f39958ba)

Solutions

Read the cause to find the failing method and parameter; add a null check (checkNotNull/requireNonNull) or annotate the parameter @Nullable if null is intentionally accepted.
Run testNulls() in isolation on the factory to iterate quickly.
Ensure every public instance method either rejects nulls explicitly or declares @Nullable on accepted-null params.

Example fix

// before
public Foo withName(String name) {
  this.name = name.toUpperCase(); // NPE later, not at boundary
  return this;
}

// after
public Foo withName(String name) {
  this.name = checkNotNull(name).toUpperCase();
  return this;
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
  factoryTester.testNulls();
} catch (AssertionError e) {
  // e.getCause() is the null-pointer AssertionError naming the failing method/param
  fail("Factory " + factory + " produced an instance failing null checks: " + e.getCause());
}

Prevention

Add explicit null checks (checkNotNull/requireNonNull) or @Nullable at every public method parameter boundary.
Run ClassSanityTester.testNulls() as part of the build for every public value type.

When it happens

Trigger: Calling ClassSanityTester.setDefault(...)/test(...)/testNulls() on a class; one of its static factory methods returns an instance whose public methods do not reject null parameters (missing @Nullable annotation + missing check).

Common situations: Adding a new public method that accepts parameters without null checks or @Nullable marks; auto-generating code; returning a wrapper/delegate that forwards nulls unsafely.

Related errors

AI-assisted analysis of google/guava@94f39958ba (2026-08-13). Data as JSON: /api/errors/d8cfe28dcd021aeb. Report an issue: GitHub.