openzipkin/zipkin · error · IllegalArgumentException

%s contains an invalid IPv6 literal

Error message

%s contains an invalid IPv6 literal

What it means

Thrown by HostAndPort.fromString for a bracketed IPv6 literal like '[garbage]:9042' whose inner address fails the Endpoint IPv6 validator. Bracketed forms are expected to contain a valid IPv6 address; anything else is rejected with IllegalArgumentException('%s contains an invalid IPv6 literal').

Source

Thrown at zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/internal/HostAndPort.java:61

  }

  @Override public String toString() {
    return "HostAndPort{host=" + host + ", port=" + port + "}";
  }

  /**
   * Constructs a host-port pair from the given string, defaulting to the indicated port if absent
   */
  public static HostAndPort fromString(String hostPort, int defaultPort) {
    if (hostPort == null) throw new NullPointerException("hostPort == null");

    String host = hostPort;
    int endHostIndex = hostPort.length();
    if (hostPort.startsWith("[")) { // Bracketed IPv6
      endHostIndex = hostPort.lastIndexOf(']') + 1;
      host = hostPort.substring(1, endHostIndex == 0 ? 1 : endHostIndex - 1);
      if (!Endpoint.newBuilder().parseIp(host)) { // reuse our IPv6 validator
        throw new IllegalArgumentException(hostPort + " contains an invalid IPv6 literal");
      }
    } else {
      int colonIndex = hostPort.indexOf(':'), nextColonIndex = hostPort.lastIndexOf(':');
      if (colonIndex >= 0) {
        if (colonIndex == nextColonIndex) { // only 1 colon
          host = hostPort.substring(0, colonIndex);
          endHostIndex = colonIndex;
        } else if (!Endpoint.newBuilder().parseIp(hostPort)) { // reuse our IPv6 validator
          throw new IllegalArgumentException(hostPort + " is an invalid IPv6 literal");
        }
      }
    }
    if (host.isEmpty()) throw new IllegalArgumentException(hostPort + " has an empty host");
    if (endHostIndex + 1 < hostPort.length() && hostPort.charAt(endHostIndex) == ':') {
      return new HostAndPort(host, validatePort(hostPort.substring(endHostIndex + 1), hostPort));
    }
    return new HostAndPort(host, defaultPort);
  }

View on GitHub (pinned to 878ce2a1fa)

Solutions

  1. Correct the IPv6 literal, e.g. '[2001:db8::1]:9042'.
  2. If the value is a hostname, remove the brackets: 'cassandra.example.com:9042'.
  3. Validate candidate IPv6 literals with a regex/Inet6Address parse before config load.

Example fix

# before
CASSANDRA_CONTACT_POINTS=[2001:db8::zz]:9042

# after
CASSANDRA_CONTACT_POINTS=[2001:db8::1]:9042
Defensive patterns

Strategy: validation

Validate before calling

static boolean isBracketedIpv6Literal(String s) {
  return s != null && s.startsWith("[") && s.contains("]")
    && Endpoint.newBuilder().parseIp(s.substring(1, s.lastIndexOf(']')));
}
if (hostPort.startsWith("[") && !isBracketedIpv6Literal(hostPort)) throw new IllegalArgumentException("Bad IPv6: " + hostPort);

Type guard

static boolean isValidBracketedIpv6(String s) { return s != null && s.startsWith("[") && s.lastIndexOf(']') > 1 && Endpoint.newBuilder().parseIp(s.substring(1, s.lastIndexOf(']'))); }

Try / catch

catch (IllegalArgumentException e) { if (e.getMessage().endsWith("contains an invalid IPv6 literal")) failConfigValidation(e.getMessage()); else throw e; }

Prevention

When it happens

Trigger: Passing '[::zz]:9042', '[]', or a bracketed host that is actually a hostname; malformed copy-paste of IPv6 contact points.

Common situations: IPv6 contact-point config where the address has a typo, missing hex digits, or the operator bracketed a DNS name by mistake.

Related errors

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/9e2255a6e0b606d0. Report an issue: GitHub.