google/gson · error · NullPointerException

key == null

Error message

key == null

What it means

Thrown by LinkedTreeMap.put(K, V) (NullPointerException 'key == null') because LinkedTreeMap is a red-black tree keyed by Comparable keys and does not support null keys. Unlike HashMap/LinkedHashMap, null cannot be ordered, so the map rejects it outright rather than guessing a position.

Source

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

    return size;
  }

  @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;

View on GitHub (pinned to 8b8628c656)

Solutions

1. Filter null keys before inserting: stream/map entries and skip key==null, or substitute a sentinel non-null key.
2. If null keys are legitimate, use a LinkedHashMap or HashMap instead of a tree-backed map; configure your Gson type target accordingly (avoid TreeMap/SortedMap for the field type).
3. Validate JSON input and reject or map null keys upstream of Gson.

Example fix

// before
LinkedTreeMap<String, Integer> m = new LinkedTreeMap<>();
m.put(null, 1); // throws

// after: filter null keys, or use HashMap
Map<String, Integer> m = new HashMap<>();
m.put(null, 1); // ok

static <V> void putSafe(Map<String, V> map, String key, V value) {
  if (key == null) return; // or throw IllegalArgumentException upstream
  map.put(key, value);
}

static boolean isNonNullOrderingCapableKey(Object key) {
  return key != null;
}

try {
  map.put(key, value);
} catch (NullPointerException e) {
  if (e.getMessage().contains("key == null")) {
    // log and skip, or fall back to a HashMap
    fallback.put(key, value);
  } else throw e;
}

When it happens

Trigger: Calling map.put(null, value) on a LinkedTreeMap instance. LinkedTreeMap is used internally by Gson when deserializing to a map whose keys must be sorted/compared; a null key in the JSON or in a manually populated LinkedTreeMap triggers it.

Common situations: JSON with a null key being deserialized into a SortedMap/TreeMap-backed type; configuring Gson with a type that resolves to LinkedTreeMap and feeding null keys; copying entries from another map without filtering nulls.

Related errors

• value == 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/c5bed3c5cbd0dcc7.json. Report an issue: GitHub.