google/gson · error · JsonSyntaxException

Failed parsing '${s}' as InetAddress; at path ${path}; to al

Error message

Failed parsing '${s}' as InetAddress; at path ${path}; to allow DNS addresses, set system property gson.allowDnsInetAddress to "true"

What it means

Thrown by Gson's InetAddress TypeAdapter when the JSON string does not look like an IP address. The adapter uses a regex (matches IPv4 dotted-quad or anything containing a colon for IPv6) and by default rejects DNS hostnames unless the system property gson.allowDnsInetAddress is set to "true", because resolving a hostname triggers a blocking DNS lookup.

Source

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

  public static final TypeAdapter<InetAddress> INET_ADDRESS =
      new TypeAdapter<InetAddress>() {

        // A pattern that matches every IP address and no DNS address. It matches plenty of things
        // that aren't either of those, which is fine. An IPv4 address is n.n.n.n where each n is a
        // non-negative integer. An IPv6 address contains at least one colon. (There are further
        // constraints in both cases, but they don't matter here.)
        private final Pattern ipAddressPattern = Pattern.compile(".*:.*|[0-9]+(\\.[0-9]+){3}");

        @Override
        public InetAddress read(JsonReader in) throws IOException {
          if (in.peek() == JsonToken.NULL) {
            in.nextNull();
            return null;
          }
          String s = in.nextString();
          if (!ipAddressPattern.matcher(s).matches()
              && !Boolean.getBoolean("gson.allowDnsInetAddress")) {
            throw new JsonSyntaxException(
                "Failed parsing '"
                    + s
                    + "' as InetAddress; at path "
                    + in.getPreviousPath()
                    + "; to allow DNS addresses, set system property gson.allowDnsInetAddress to"
                    + " \"true\"");
          }
          @SuppressWarnings("AddressSelection")
          InetAddress addr = InetAddress.getByName(s);
          return addr;
        }

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

View on GitHub (pinned to 310ac341f2)

Solutions

If DNS resolution during deserialization is acceptable, set system property gson.allowDnsInetAddress=true (e.g. -Dgson.allowDnsInetAddress=true at JVM startup, or System.setProperty(...) before parsing).
Deserialize the field as String and resolve with InetAddress.getByName(...) explicitly in your own code where you can control timeouts and error handling.
Register a custom TypeAdapter<InetAddress> that resolves hostnames with a configured DNS resolver and timeout.
Fix the source data to contain IP addresses (e.g. 192.0.2.1 or 2001:db8::1).

Example fix

// before
public class Host { public InetAddress address; }
// JSON: {"address":"my-service.internal"} -> fails

// option 1: allow DNS at JVM level
java -Dgson.allowDnsInetAddress=true -jar app.jar

// option 2: deserialize as String, resolve explicitly
public class Host {
  public String address;
  public InetAddress resolved() throws UnknownHostException {
    return InetAddress.getByName(address);
  }
}

Defensive patterns

Strategy: validation

Validate before calling

private static final Pattern IP =
  Pattern.compile("^[0-9]+(\\.[0-9]+){3}$|:.*"); // mirrors gson's check
String raw = jsonNode.get("address").getAsString();
boolean allowDns = Boolean.getBoolean("gson.allowDnsInetAddress");
if (!allowDns && !IP.matcher(raw).matches()) {
  throw new IllegalArgumentException("Not an IP and DNS disabled: " + raw);
}

Try / catch

try {
  return gson.fromJson(json, Host.class);
} catch (JsonSyntaxException e) {
  if (e.getMessage().contains("as InetAddress")) {
    // either fix data to IP form, or set gson.allowDnsInetAddress=true and retry
    throw new IllegalArgumentException("InetAddress needs IP or DNS allowed", e);
  }
  throw e;
}

Prevention

Deserialize hostnames as String and resolve explicitly with a timeout-aware resolver.
Set -Dgson.allowDnsInetAddress=true only in environments where blocking DNS in parse is acceptable.
Run unit tests asserting both IPv4 and IPv6 inputs parse cleanly.
Document which fields are IP-only vs DNS-capable to prevent confusion.

When it happens

Trigger: Deserializing a field of type java.net.InetAddress (or Inet4Address/Inet6Address subtypes) from a JSON value containing a hostname like "example.com" or "my-host", which fails the ipAddressPattern regex and the system property is not set.

Common situations: Config payloads that carry hostnames rather than IPs; service discovery records; ingesting machine inventories where the JSON has DNS names; default Gson config where DNS lookups during deserialization are intentionally disabled to avoid I/O on the parsing thread.

Related errors

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