GoogleContainerTools/jib · error · NumberFormatException

Port number '<port>' is out of usual range (1-65535).

Error message

Port number '<port>' is out of usual range (1-65535).

What it means

Ports.parse warns (as a NumberFormatException) when the port or range falls outside the usual TCP/UDP range 1-65535, i.e. min < 1 or max > 65535. Even though a syntactically valid number was given, it cannot be a real network port, so the library rejects it with this explicit message.

Source

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

      }

      // 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(
            "Invalid port range '" + port + "'; smaller number must come first.");
      }

      // Warn for possibly invalid port numbers
      if (min < 1 || max > 65535) {
        throw new NumberFormatException(
            "Port number '" + port + "' is out of usual range (1-65535).");
      }

      for (int portNumber = min; portNumber <= max; portNumber++) {
        result.add(Port.parseProtocol(portNumber, protocol));
      }
    }

    return result;
  }

  private Ports() {}
}

View on GitHub (pinned to fb949e2676)

Solutions

1. Use port numbers in 1-65535; fix typos like 80800 -> 8080.
2. Exclude port 0; Jib does not assign ephemeral ports via exposedPorts config.
3. Clamp or validate values in your config layer: check 1 <= min && max <= 65535 before calling parse.
4. For a range spanning the boundary, split into valid sub-ranges within 1-65535.

Example fix

// before
builder.addExpose("80-99999");
// after
int max = Math.min(99999, 65535);
builder.addExpose("80-" + max); // "80-65535"

if (min < 1 || max > 65535) throw new IllegalArgumentException("ports must be in 1-65535: " + spec);

null

try { Ports.parse(ports); } catch (NumberFormatException e) { /* flag out-of-range entries to the user before building */ }

When it happens

Trigger: Calling Ports.parse with values like '0', '-1', '70000', '0-8080', or '80-99999' where any bound is below 1 or above 65535.

Common situations: Using port 0 expecting dynamic-port semantics (unsupported here); paste errors adding an extra digit (80800); config driven by unvalidated user input; confusing internal service codes with network ports.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Invalid port configuration: '<port>'. Make sure the port is
• Invalid port range '<port>'; smaller number must come first.
• Invalid port configuration: '" + port + "'.
• octalPermissions must be a 3-digit octal number (000-777)
• The class file (${jarEntry}) is of an invalid format.

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