google/gson · error · JsonParseException

null is not allowed as value for record component '" + field

Error message

null is not allowed as value for record component '" + fieldName + "' of primitive type; at path " + reader.getPath()

What it means

Thrown while deserializing a Java record when a JSON null is encountered for a component whose type is a primitive (int, long, boolean, etc.). Records cannot store null for primitives and the canonical constructor cannot accept null, so Gson aborts with a JsonParseException including the field name and the reader path.

Source

Thrown at gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java:262

          fieldValue = field.get(source);
        }

        @SuppressWarnings("ReferenceEquality")
        boolean isSameObject = fieldValue == source;
        if (isSameObject) {
          // avoid direct recursion
          return;
        }
        writer.name(serializedName);
        writeTypeAdapter.write(writer, fieldValue);
      }

      @Override
      void readIntoArray(JsonReader reader, int index, Object[] target)
          throws IOException, JsonParseException {
        Object fieldValue = typeAdapter.read(reader);
        if (fieldValue == null && isPrimitive) {
          throw new JsonParseException(
              "null is not allowed as value for record component '"
                  + fieldName
                  + "' of primitive type; at path "
                  + reader.getPath());
        }
        target[index] = fieldValue;
      }

      @Override
      void readIntoField(JsonReader reader, Object target)
          throws IOException, IllegalAccessException {
        Object fieldValue = typeAdapter.read(reader);
        if (fieldValue != null || !isPrimitive) {
          if (blockInaccessible) {
            checkAccessible(target, field);
          } else if (isStaticFinalField) {
            // Reflection does not permit setting value of `static final` field, even after calling
            // `setAccessible`

View on GitHub (pinned to 8b8628c656)

Solutions

Change the record component from primitive to its boxed wrapper (int -> Integer, boolean -> Boolean) so null is acceptable.
Pre-process or sanitize the JSON to replace nulls with defaults before deserialization.
Register a custom TypeAdapter that maps null to a default primitive value (e.g., 0).
Negotiate with the data source to always emit a concrete value for the field.

Example fix

// before
public record User(int id, String name) {}
gson.fromJson("{\"id\":null,\"name\":\"A\"}", User.class); // throws

// after
public record User(Integer id, String name) {}

Defensive patterns

Strategy: validation

Validate before calling

// Reject null values for primitive record components before deserialization
JsonObject o = JsonParser.parseString(json).getAsJsonObject();
for (RecordComponent c : User.class.getRecordComponents()) {
  if (c.getType().isPrimitive() && o.has(c.getName()) && o.get(c.getName()).isJsonNull()) {
    throw new IllegalArgumentException("null for primitive " + c.getName());
  }
}

Type guard

null

Try / catch

try {
  gson.fromJson(json, User.class);
} catch (JsonParseException e) {
  if (e.getMessage().contains("null is not allowed as value for record component")) {
    // coerce null -> default or ask caller for clean data
  } else throw e;
}

Prevention

Use boxed wrappers (Integer/Boolean) for record components that may receive null.
Validate incoming JSON against a schema before handing it to Gson.
Keep a list of primitive record components and check them explicitly for nulls.
Prefer Integer/Long over int/long for external API DTOs.

When it happens

Trigger: Triggered in BoundField.readIntoArray (ReflectiveTypeAdapterFactory.java:261) when typeAdapter.read(reader) returns null but isPrimitive is true. The JSON document explicitly has "field": null (or omits/produces null via a custom adapter) for a primitive record component such as `int id`.

Common situations: API responses that emit null for numeric/boolean fields when data is missing; nullable database columns mapped to primitive record components; upstream services that conditionally include fields; strict-mode configs where clients send `"count": null`.

Related errors

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