google/gson · error · NullPointerException

Element must be non-null

Error message

Element must be non-null

What it means

Thrown by NonNullElementWrapperList.nonNull(E) (NullPointerException 'Element must be non-null') when add(int, E) or set(int, E) receives a null element. NonNullElementWrapperList wraps an ArrayList and enforces a no-null-elements contract on all mutating operations; reads and queries (contains/indexOf) are exempt so they behave like normal List null handling.

Source

Thrown at gson/src/main/java/com/google/gson/internal/NonNullElementWrapperList.java:52

  @SuppressWarnings("NonApiType")
  public NonNullElementWrapperList(ArrayList<E> delegate) {
    this.delegate = Objects.requireNonNull(delegate);
  }

  @Override
  public E get(int index) {
    return delegate.get(index);
  }

  @Override
  public int size() {
    return delegate.size();
  }

  private E nonNull(E element) {
    if (element == null) {
      throw new NullPointerException("Element must be non-null");
    }
    return element;
  }

  @Override
  public E set(int index, E element) {
    return delegate.set(index, nonNull(element));
  }

  @Override
  public void add(int index, E element) {
    delegate.add(index, nonNull(element));
  }

  @Override
  public E remove(int index) {
    return delegate.remove(index);
  }

View on GitHub (pinned to 8b8628c656)

Solutions

1. Filter nulls before adding: elements.stream().filter(Objects::nonNull).forEach(list::add).
2. Substitute a non-null placeholder (e.g. JsonNull.INSTANCE if the API accepts it, or an empty/default element).
3. Use a plain ArrayList if null elements are genuinely required.

Example fix

// before
NonNullElementWrapperList<String> list = new NonNullElementWrapperList<>(new ArrayList<>());
list.add(null); // throws

// after: filter nulls
for (String s : source) if (s != null) list.add(s);

static <E> void addNonNull(List<E> list, E e) {
  if (e != null) list.add(e);
}
// usage: source.forEach(e -> addNonNull(list, e));

static <E> boolean isNonNullOrSkip(E e) { return e != null; }

try {
  list.add(e);
} catch (NullPointerException ex) {
  if (ex.getMessage().contains("non-null")) {
    // skip null or substitute a default element
  } else throw ex;
}

When it happens

Trigger: Calling list.add(index, null) or list.set(index, null) on a NonNullElementWrapperList. Gson uses this list internally (e.g. for JsonArray element storage in configurations that reject nulls); adding a null JsonElement triggers the guard.

Common situations: Deserializing JSON arrays containing nulls into a JsonArray or list type that disallows null elements; programmatically building a list/array and appending null for missing items; mixing nullable sources into a non-null list.

Related errors

• key == null
• value == null
• {className} is not Comparable
• null is not allowed as value for record component '" + field
• null is not a valid AtomicLongArray element

AI-assisted analysis of google/gson@8b8628c656 (2026-08-04). Data as JSON: /data/errors/1f9424faee099cb4.json. Report an issue: GitHub.