phacility/phabricator · warning · PhutilArgumentUsageException

Specified "--min-failures" must not be larger than specified

Error message

Specified "--min-failures" must not be larger than specified "--max-failures".

What it means

Thrown by worker management workflows when `--min-failures` is greater than `--max-failures`. The pair defines an inclusive range for filtering tasks by failure count; an inverted range can never match and the workflow rejects it as an argument error before querying. Only fires when both bounds are supplied, since a single bound alone cannot be contradictory.

Source

Thrown at src/infrastructure/daemon/workers/management/PhabricatorWorkerManagementWorkflow.php:123

    if ($container_names) {
      $any_constraints = true;
      $container_phids = $this->loadObjectPHIDsFromArguments($container_names);
    } else {
      $container_phids = array();
    }

    if ($object_names) {
      $any_constraints = true;
      $object_phids = $this->loadObjectPHIDsFromArguments($object_names);
    } else {
      $object_phids = array();
    }

    if (($min_failures !== null) || ($max_failures !== null)) {
      $any_constraints = true;
      if (($min_failures !== null) && ($max_failures !== null)) {
        if ($min_failures > $max_failures) {
          throw new PhutilArgumentUsageException(
            pht(
              'Specified "--min-failures" must not be larger than '.
              'specified "--max-failures".'));
        }
      }
    }

    if (($min_priority !== null) || ($max_priority !== null)) {
      $any_constraints = true;
      if (($min_priority !== null) && ($max_priority !== null)) {
        if ($min_priority > $max_priority) {
          throw new PhutilArgumentUsageException(
            pht(
              'Specified "--min-priority" may not be larger than '.
              'specified "--max-priority".'));
        }
      }
    }

View on GitHub (pinned to 5720a38cfe)

Solutions

Swap the values so min <= max: `--min-failures 3 --max-failures 10`
Use a single bound if you only need one side of the range (e.g. just `--min-failures 5`)
In generated commands, assert min <= max before shelling out

Example fix

# before
./bin/worker retry --min-failures 10 --max-failures 3

# after
./bin/worker retry --min-failures 3 --max-failures 10

Defensive patterns

Strategy: validation

Validate before calling

if ($min_failures !== null && $max_failures !== null
    && $min_failures > $max_failures) {
  throw new InvalidArgumentException(
    sprintf('--min-failures (%d) must not exceed --max-failures (%d)',
      $min_failures, $max_failures));
}

Prevention

Assert min <= max in any script templating both bounds
Prefer a single bound when only one side of the range matters

When it happens

Trigger: `./bin/worker retry --min-failures 10 --max-failures 3`, or any invocation where the min flag's integer exceeds the max flag's integer. Common when retrying failed tasks: `./bin/worker retry --min-failures 5 --max-failures 2 --class ...`.

Common situations: Operators swapping the order of the two flags when editing a documented command; scripts templating both values from separate config keys that drift apart; misunderstandings about whether the bounds are (min, max) or (max, min).

Related errors

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/b5426a37c4b75942. Report an issue: GitHub.