What causes "Invalid port range ' '; smaller number must come first." in GoogleContainerTools/jib?

Rewrite the range so the smaller number comes first: '8000-9000' instead of '9000-8000'.

GoogleContainerTools/jib · error · NumberFormatException

Invalid port range '<port>'; smaller number must come first.

Error message

Invalid port range '<port>'; smaller number must come first.

What it means

Ports.parse also validates the order of a port range. When a range like '9000-8000' is given (min parsed greater than max parsed), it throws NumberFormatException with 'Invalid port range ... smaller number must come first.' The library requires ranges in ascending order to keep the exposed port list deterministic.

Source

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

        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(
            "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

Rewrite the range so the smaller number comes first: '8000-9000' instead of '9000-8000'.
Normalize programmatically with Math.min/Math.max before formatting the range string.
Validate ranges in your config layer before invoking Ports.parse.
If both orders are acceptable input, swap and re-format rather than rejecting the build.

Example fix

// before
builder.addExpose("9000-8000");
// after
int a = 9000, b = 8000;
builder.addExpose(Math.min(a, b) + "-" + Math.max(a, b)); // "8000-9000"

Defensive patterns

Strategy: validation

Validate before calling

if (min > max) throw new IllegalArgumentException("range must be min-max, got " + min + "-" + max);

Type guard

null

Try / catch

try { Ports.parse(List.of(spec)); } catch (NumberFormatException e) { /* normalize via Math.min/max and retry */ }

Prevention

Generate range strings with Math.min/Math.max
Review hand-written ranges for reversed bounds
Validate port config at load time
Keep min/max variables clearly named to avoid swaps

When it happens

Trigger: Calling Ports.parse with a range string whose lower bound is greater than its upper bound, e.g. '9000-8000', '65535-1024'.

Common situations: Programmatically generating ranges from min/max variables that are swapped; hand-written config where the range was typed backwards; templating that interpolates high-first ordering.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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