openzipkin/zipkin · error · IllegalArgumentException

invalid port

Error message

invalid port 

What it means

Endpoint.Builder.port(Integer) throws IllegalArgumentException('invalid port') when the boxed port value exceeds 0xffff (65535). Ports are unsigned 16-bit; the builder accepts null (unknown) and coerces values <= 0 to zero, but a value above 65535 cannot be represented and is rejected. The message intentionally shows the offending number.

Source

Thrown at zipkin/src/main/java/zipkin2/Endpoint.java:264

        byte[] addressBytes = textToNumericFormatV6(ipString);
        if (addressBytes == null) return false;
        ipv6 = writeIpV6(addressBytes); // ensures consistent format
        ipv6Bytes = addressBytes;
      } else {
        return false;
      }
      return true;
    }

    /**
     * Use this to set the port to an externally defined value.
     *
     * @param port port associated with the endpoint. zero coerces to null (unknown)
     * @see Endpoint#port()
     */
    public Builder port(@Nullable Integer port) {
      if (port != null) {
        if (port > 0xffff) throw new IllegalArgumentException("invalid port " + port);
        if (port <= 0) port = 0;
      }
      this.port = port != null ? port : 0;
      return this;
    }

    /** Sets {@link Endpoint#portAsInt()} */
    public Builder port(int port) {
      if (port > 0xffff) throw new IllegalArgumentException("invalid port " + port);
      if (port < 0) port = 0;
      this.port = port;
      return this;
    }

    public Endpoint build() {
      return new Endpoint(this);
    }

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Correct the port to the real 1-65535 value the service listens on.
2. Validate before setting: if (port != null && (port < 0 || port > 0xffff)) throw/log at the config layer.
3. If the port is unknown, pass port(0) or leave it unset instead of encoding a sentinel like 99999.

Example fix

// before
Endpoint e = Endpoint.newBuilder().ip("10.0.0.1").port(80800).serviceName("web").build();

// after
Endpoint e = Endpoint.newBuilder().ip("10.0.0.1").port(8080).serviceName("web").build();

if (port != null && (port > 0xFFFF)) throw new IllegalArgumentException("port out of range: " + port);
builder.port(port);

try { builder.port(port); } catch (IllegalArgumentException e) { /* surface config error with the endpoint/service name */ }

When it happens

Trigger: Calling endpointBuilder.port(70000) or port(someInt) where the value came from misparsed configuration (e.g. a port read from a string with extra digits, or an int carrying an IP octet by mistake).

Common situations: Config typos like port 80800; parsing failures where -1 from an unset value gets transformed into a large positive; copying a port+offset calculation that overflows the valid range.

Related errors

• %s has an invalid port
• endTs <= 0
• value == null
• parent == null
• child == null

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