google/gson · error · JsonSyntaxException

Failed parsing '" + s + "' as UUID; at path " + in.getPrevio

Error message

Failed parsing '" + s + "' as UUID; at path " + in.getPreviousPath()

What it means

Gson's UUID TypeAdapter reads the JSON string and calls java.util.UUID.fromString, which requires the canonical 36-character hyphenated form. Any deviation throws IllegalArgumentException, wrapped by Gson as JsonSyntaxException with the bad string and JSON path.

Source

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

        }
      };

  public static final TypeAdapterFactory INET_ADDRESS_FACTORY =
      newTypeHierarchyFactory(InetAddress.class, INET_ADDRESS);

  public static final TypeAdapter<UUID> UUID =
      new TypeAdapter<UUID>() {
        @Override
        public UUID read(JsonReader in) throws IOException {
          if (in.peek() == JsonToken.NULL) {
            in.nextNull();
            return null;
          }
          String s = in.nextString();
          try {
            return java.util.UUID.fromString(s);
          } catch (IllegalArgumentException e) {
            throw new JsonSyntaxException(
                "Failed parsing '" + s + "' as UUID; at path " + in.getPreviousPath(), e);
          }
        }

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

  public static final TypeAdapterFactory UUID_FACTORY = newFactory(UUID.class, UUID);

  public static final TypeAdapter<Currency> CURRENCY =
      new TypeAdapter<Currency>() {
        @Override
        public Currency read(JsonReader in) throws IOException {
          String s = in.nextString();
          try {

View on GitHub (pinned to 8b8628c656)

Solutions

Normalize the input to canonical form before Gson: trim, strip 'urn:uuid:'/'{}', re-insert hyphens for 32-char hex.
Register a custom TypeAdapter<UUID> that performs the normalization and then calls UUID.fromString.
Correct the upstream producer to emit canonical 8-4-4-4-12 UUIDs.

Example fix

// before
UUID id = gson.fromJson("\"550e8400e29b41d4a716446655440000\"", UUID.class);

// after
Gson gson = new GsonBuilder().registerTypeHierarchyAdapter(UUID.class, new JsonDeserializer<UUID>() {
    @Override public UUID deserialize(JsonElement j, Type t, JsonDeserializationContext c) {
        String s = j.getAsString().replace("urn:uuid:", "").replace("{", "").replace("}", "").trim();
        if (s.length() == 32) s = s.replaceAll("(.{8})(.{4})(.{4})(.{4})(.{12})", "$1-$2-$3-$4-$5");
        return UUID.fromString(s);
    }
}).create();

Defensive patterns

Strategy: validation

Validate before calling

boolean isParsableUuid(String s) {
  if (s == null) return false;
  try { UUID.fromString(s); return true; } catch (IllegalArgumentException e) { return false; }
}

Type guard

static boolean isCanonicalUuid(String s) {
  return s != null && s.matches("[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}");
}

Try / catch

try {
  UUID u = gson.fromJson(json, UUID.class);
} catch (JsonSyntaxException e) {
  // normalize (strip braces/urn, re-hyphenate 32-hex) and retry once
}

Prevention

Normalize incoming UUIDs to canonical 8-4-4-4-12 hex before Gson.
Register a tolerant UUID TypeAdapter once at Gson construction.
Validate at API boundaries with a shared helper.

When it happens

Trigger: Deserializing a JSON string into a UUID field when the string is not a valid 8-4-4-4-12 hex representation (wrong length, missing hyphens, non-hex chars, extra braces).

Common situations: Producer emits a stripped UUID (no hyphens), a URN prefix 'urn:uuid:...', curly braces from .NET GUIDs, uppercase being fine but extra whitespace, or a different field mistakenly mapped.

Related errors

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