google/gson · error · NullPointerException

value == null

Error message

value == null

What it means

Thrown by LinkedTreeMap.put(K, V) (NullPointerException 'value == null') when allowNullValues is false. The default no-arg constructor enables null values, but the constructor LinkedTreeMap(boolean allowNullValues) or LinkedTreeMap(comparator, false) disables them, so putting a null value violates the map's contract and is rejected immediately.

Source

Thrown at gson/src/main/java/com/google/gson/internal/LinkedTreeMap.java:112

  @Override
  public V get(Object key) {
    Node<K, V> node = findByObject(key);
    return node != null ? node.value : null;
  }

  @Override
  public boolean containsKey(Object key) {
    return findByObject(key) != null;
  }

  @CanIgnoreReturnValue
  @Override
  public V put(K key, V value) {
    if (key == null) {
      throw new NullPointerException("key == null");
    }
    if (value == null && !allowNullValues) {
      throw new NullPointerException("value == null");
    }
    Node<K, V> created = find(key, true);
    V result = created.value;
    created.value = value;
    return result;
  }

  @Override
  public void clear() {
    root = null;
    size = 0;
    modCount++;

    // Clear iteration order
    Node<K, V> header = this.header;
    header.next = header.prev = header;
  }

View on GitHub (pinned to 8b8628c656)

Solutions

1. Construct the map allowing null values if nulls are expected: new LinkedTreeMap<>(true) or the no-arg constructor.
2. Default missing/null values to a non-null placeholder before insertion (e.g. empty string, 0, Optional.empty).
3. Configure Gson not to serialize nulls so omitted fields are skipped rather than written as null.

Example fix

// before
LinkedTreeMap<String, String> m = new LinkedTreeMap<>(false);
m.put("k", null); // throws

// after: allow null values, or supply a default
LinkedTreeMap<String, String> m = new LinkedTreeMap<>(true);
m.put("k", null); // ok

LinkedTreeMap<String, String> map = new LinkedTreeMap<>(true); // allow null values
// or guard each put:
static <V> void putSafeValue(LinkedTreeMap<String, V> m, String k, V v, V fallback) {
  m.put(k, v != null ? v : fallback);
}

null

try {
  map.put(k, v);
} catch (NullPointerException e) {
  if (e.getMessage().contains("value == null")) {
    map.put(k, defaultValue);
  } else throw e;
}

When it happens

Trigger: Constructing LinkedTreeMap with allowNullValues=false (directly or via LinkedTreeMap(false)) and calling put(key, null). Also reached when Gson builds a LinkedTreeMap with null values disallowed and the JSON omits a value or contains an explicit null for an entry value while the target type forbids nulls.

Common situations: Gson configured to serialize nulls (serializeNulls()) deserializing into a type that uses a null-disallowing tree map; explicitly constructing LinkedTreeMap(false) to harden a map and then inserting null; merging partial data with missing fields.

Related errors

• key == null
• {className} is not Comparable
• Element must be non-null
• Deserialization is unsupported
• duplicate key: {key}

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