GoogleContainerTools/jib · error · NumberFormatException

Invalid port configuration: '<port>'. Make sure the port is

Error message

Invalid port configuration: '<port>'. Make sure the port is a single number or a range of two numbers separated with a '-', with or without protocol specified (e.g. '<portNum>/tcp' or '<portNum>/udp').

What it means

Ports.parse validates each port specification string against a regex allowing a single number or a range 'min-max', optionally followed by /tcp or /udp. If a string does not match this pattern, it throws NumberFormatException with a message explaining the accepted formats. The exception happens before any port is added to the result set.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/api/Ports.java:56

   * Converts/validates a list of strings representing port ranges to an expanded list of {@link
   * Port}s.
   *
   * <p>For example: ["1000", "2000-2002"] will expand to a list of {@link Port}s with the port
   * numbers [1000, 2000, 2001, 2002]
   *
   * @param ports the list of port numbers/ranges, with an optional protocol separated by a '/'
   *     (defaults to TCP if missing).
   * @return the ports as a list of {@link Port}
   * @throws NumberFormatException if any of the ports are in an invalid format or out of range
   */
  public static Set<Port> parse(List<String> ports) throws NumberFormatException {
    Set<Port> result = new HashSet<>();

    for (String port : ports) {
      Matcher matcher = portPattern.matcher(port);

      if (!matcher.matches()) {
        throw new NumberFormatException(
            "Invalid port configuration: '"
                + port
                + "'. Make sure the port is a single number or a range of two numbers separated "
                + "with a '-', with or without protocol specified (e.g. '<portNum>/tcp' or "
                + "'<portNum>/udp').");
      }

      // Parse protocol
      int min = Integer.parseInt(matcher.group(1));
      int max = min;
      if (!Strings.isNullOrEmpty(matcher.group(2))) {
        max = Integer.parseInt(matcher.group(2));
      }
      String protocol = matcher.group(3);

      // Error if configured as 'max-min' instead of 'min-max'
      if (min > max) {
        throw new NumberFormatException(

View on GitHub (pinned to fb949e2676)

Solutions

1. Use valid formats: '80', '80-90', '8080/tcp', '53/udp', '1000-2000/udp'.
2. Fix Docker-style mappings by splitting on ':' and taking the container port ('8080:80' -> '80').
3. Trim strings and remove empty entries before passing the list to parse.
4. Lowercase the protocol suffix (/tcp, /udp) to match the pattern.
5. Add pre-validation with a regex like ^\d+(-\d+)?(/(tcp|udp))?$ in your config loading code.

Example fix

// before
List<String> ports = env("PORTS").split(","); // may contain "" or "8080:80"
PortList.addAll(Ports.parse(ports));
// after
List<String> ports = Arrays.stream(env("PORTS").split(","))
    .map(String::trim).filter(s -> !s.isEmpty())
    .map(s -> s.contains(":") ? s.substring(s.indexOf(':') + 1) : s)
    .collect(Collectors.toList());
PortList.addAll(Ports.parse(ports));

Pattern OK = Pattern.compile("^\\d+(-\\d+)?(/(tcp|udp))?$");
for (String p : ports) { if (!OK.matcher(p.trim()).matches()) throw new IllegalArgumentException("bad port: " + p); }

null

try { Set<Port> parsed = Ports.parse(ports); } catch (NumberFormatException e) { log.error("Bad port spec: {}", e.getMessage()); throw new ConfigException(e); }

When it happens

Trigger: Calling Ports.parse(...) with malformed strings such as "80x443", "http", "80-90-100", " 80", "80/https", or "8080/" (trailing slash, whitespace, letters, wrong separators).

Common situations: Docker-compose-style port mappings like '8080:80' pasted into Jib's exposedPorts config; environment-variable-driven port lists containing empty strings; YAML/JSON config with protocol typos like '/TCP' uppercase.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid port range '<port>'; smaller number must come first.
• Port number '<port>' is out of usual range (1-65535).
• Invalid port configuration: '" + port + "'.
• 'registryMirrors.registry' property is missing
• 'registryMirrors.mirrors' property is missing

AI-assisted analysis of GoogleContainerTools/jib@fb949e2676 (2026-09-06). Data as JSON: /api/errors/4e84b4577c898821. Report an issue: GitHub.