google/gson · error · JsonSyntaxException

Expecting character, got: ${str}; at ${path}

Error message

Expecting character, got: ${str}; at ${path}

What it means

The CHARACTER adapter reads a JSON string and expects exactly one character. If the string is empty or has more than one character, Gson cannot unambiguously map it to a char and throws JsonSyntaxException.

Source

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

  }

  public static final TypeAdapter<Number> FLOAT = new FloatAdapter(false);
  public static final TypeAdapter<Number> FLOAT_STRICT = new FloatAdapter(true);

  public static final TypeAdapter<Number> DOUBLE = new DoubleAdapter(false);
  public static final TypeAdapter<Number> DOUBLE_STRICT = new DoubleAdapter(true);

  public static final TypeAdapter<Character> CHARACTER =
      new TypeAdapter<Character>() {
        @Override
        public Character read(JsonReader in) throws IOException {
          if (in.peek() == JsonToken.NULL) {
            in.nextNull();
            return null;
          }
          String str = in.nextString();
          if (str.length() != 1) {
            throw new JsonSyntaxException(
                "Expecting character, got: " + str + "; at " + in.getPreviousPath());
          }
          return str.charAt(0);
        }

        @Override
        public void write(JsonWriter out, Character value) throws IOException {
          out.value(value == null ? null : String.valueOf(value));
        }
      };

  public static final TypeAdapterFactory CHARACTER_FACTORY =
      newFactory(char.class, Character.class, CHARACTER);

  public static final TypeAdapter<String> STRING =
      new TypeAdapter<String>() {
        @Override
        public String read(JsonReader in) throws IOException {

View on GitHub (pinned to 310ac341f2)

Solutions

1. Change the field type from char/Character to String to accept variable-length values
2. Pre-validate that the JSON string has exactly one character before deserializing
3. Register a custom TypeAdapter that takes the first character or provides a default

Example fix

// before
class Config { char grade; }
gson.fromJson("{\"grade\":\"A+\"}", Config.class); // throws — two chars

// after
class Config { String grade; }

// Validate that the JSON value is a single character before deserializing into char
public static boolean isSingleChar(JsonElement e) {
    return e.isJsonPrimitive() && e.getAsString().length() == 1;
}

try {
    Config c = gson.fromJson(json, Config.class);
} catch (JsonSyntaxException e) {
    if (e.getMessage().contains("Expecting character")) {
        // change the field type to String or pre-validate input
    }
}

When it happens

Trigger: Deserializing a JSON string like "" (empty) or "ab" (two chars) into a char or Character field.

Common situations: An API returns an empty string for an optional char field; a multi-character string is mistakenly mapped to a char field; enum-like codes longer than one character modeled as char.

Related errors

• Invalid bitset value type: ${tokenType}; at path ${path}
• Invalid bitset value ${intValue}, expected 0 or 1; at path $
• cannot deserialize ${baseType} because it does not define a
• cannot deserialize ${baseType} subtype named ${label}; did y
• Failed to parse date [${input}]: ${fail.getMessage()}

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