google/gson · error · JsonSyntaxException

Invalid bitset value ${intValue}, expected 0 or 1; at path $

Error message

Invalid bitset value ${intValue}, expected 0 or 1; at path ${path}

What it means

The built-in BitSet adapter reads a JSON array and expects each element to be 0 or 1 (from NUMBER or STRING tokens). If a numeric element is any other value, it throws JsonSyntaxException because the bit value cannot be determined.

Source

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

      new TypeAdapter<BitSet>() {
        @Override
        public BitSet read(JsonReader in) throws IOException {
          BitSet bitset = new BitSet();
          in.beginArray();
          int i = 0;
          JsonToken tokenType = in.peek();
          while (tokenType != JsonToken.END_ARRAY) {
            boolean set;
            switch (tokenType) {
              case NUMBER:
              case STRING:
                int intValue = in.nextInt();
                if (intValue == 0) {
                  set = false;
                } else if (intValue == 1) {
                  set = true;
                } else {
                  throw new JsonSyntaxException(
                      "Invalid bitset value "
                          + intValue
                          + ", expected 0 or 1; at path "
                          + in.getPreviousPath());
                }
                break;
              case BOOLEAN:
                set = in.nextBoolean();
                break;
              default:
                throw new JsonSyntaxException(
                    "Invalid bitset value type: " + tokenType + "; at path " + in.getPath());
            }
            if (set) {
              bitset.set(i);
            }
            ++i;
            tokenType = in.peek();

View on GitHub (pinned to 310ac341f2)

Solutions

1. Pre-validate the JSON array to ensure all numeric elements are 0 or 1 before deserializing
2. Register a custom TypeAdapter<BitSet> that maps a wider range of values (e.g. non-zero = true)
3. Fix the source data to emit only 0 and 1 values

Example fix

// before
gson.fromJson("[0, 2, 1]", BitSet.class); // throws on value 2

// after — use boolean representation or fix data
gson.fromJson("[false, true, true]", BitSet.class); // booleans are accepted

// Validate BitSet array values before deserializing
public static void validateBitSet(JsonArray arr) {
    for (JsonElement e : arr) {
        if (e.isJsonPrimitive() && e.getAsJsonPrimitive().isNumber()) {
            int v = e.getAsInt();
            if (v != 0 && v != 1) {
                throw new IllegalArgumentException("Invalid bitset value: " + v + " (expected 0 or 1)");
            }
        }
    }
}

try {
    BitSet bs = gson.fromJson(json, BitSet.class);
} catch (JsonSyntaxException e) {
    if (e.getMessage().contains("Invalid bitset value")) {
        // sanitize input or register a custom BitSet adapter
    }
}

When it happens

Trigger: Deserializing a JSON array like [0, 2, 1] into a BitSet field — the value 2 is neither 0 nor 1.

Common situations: An API returns integer values other than 0/1 for a bitmask field; confusion between BitSet and general integer-array representations; data from a system that uses -1/0/1 conventions.

Related errors

• Invalid bitset value type: ${tokenType}; at path ${path}
• Expecting number, got: ${jsonToken}; at path ${path}
• Lossy conversion from ${intValue} to byte; at path ${path}
• Lossy conversion from ${intValue} to short; at path ${path}
• null is not a valid AtomicLongArray element

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