google/gson · error · JsonSyntaxException

Lossy conversion from ${intValue} to byte; at path ${path}

Error message

Lossy conversion from ${intValue} to byte; at path ${path}

What it means

The BYTE adapter reads a JSON number as an int and rejects values outside the range [-128, 255] (the extended upper bound supports unsigned byte values). Values outside this range would lose data when cast to byte, so Gson throws JsonSyntaxException rather than silently truncating.

Source

Thrown at gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java:209

  public static final TypeAdapter<Number> BYTE =
      new TypeAdapter<Number>() {
        @Override
        public Number read(JsonReader in) throws IOException {
          if (in.peek() == JsonToken.NULL) {
            in.nextNull();
            return null;
          }

          int intValue;
          try {
            intValue = in.nextInt();
          } catch (NumberFormatException e) {
            throw new JsonSyntaxException(e);
          }
          // Allow up to 255 to support unsigned values
          if (intValue > 255 || intValue < Byte.MIN_VALUE) {
            throw new JsonSyntaxException(
                "Lossy conversion from " + intValue + " to byte; at path " + in.getPreviousPath());
          }
          return (byte) intValue;
        }

        @Override
        public void write(JsonWriter out, Number value) throws IOException {
          if (value == null) {
            out.nullValue();
          } else {
            out.value(value.byteValue());
          }
        }
      };

  public static final TypeAdapterFactory BYTE_FACTORY = newFactory(byte.class, Byte.class, BYTE);

  public static final TypeAdapter<Number> SHORT =

View on GitHub (pinned to 310ac341f2)

Solutions

Change the field type from byte/Byte to int/Integer or short/Short to accommodate the value range
Pre-validate the numeric range of the JSON value before deserializing
Register a custom TypeAdapter that clamps or rejects out-of-range values

Example fix

// before
class Config { byte port; } // max 255
gson.fromJson("{\"port\":300}", Config.class); // throws

// after
class Config { int port; }

Defensive patterns

Strategy: validation

Validate before calling

// Validate numeric range before deserializing into a byte field
public static boolean isValidByte(int value) {
    return value >= Byte.MIN_VALUE && value <= 255;
}
// Usage: check before calling fromJson, or model the field as int instead

Try / catch

try {
    Config c = gson.fromJson(json, Config.class);
} catch (JsonSyntaxException e) {
    if (e.getMessage().contains("Lossy conversion") && e.getMessage().contains("byte")) {
        // widen the field type to int or short
    }
}

Prevention

Model fields as int or short when the value range may exceed [-128, 255]
Validate numeric ranges at the API boundary before deserialization
Review byte fields in DTOs for potential overflow from external data

When it happens

Trigger: Deserializing a JSON number like 300 or -200 into a byte or Byte field.

Common situations: An API returns an int ID or counter that occasionally exceeds the byte range; a field modeled as byte that should be int or short; unsigned/signed confusion.

Related errors

AI-assisted analysis of google/gson@310ac341f2 (2026-08-10). Data as JSON: /api/errors/351ec2bd08dbd0d9. Report an issue: GitHub.