What causes "Specified "--limit" must be a positive integer." in phacility/phabricator?

Pass a positive integer such as `--limit 100`

phacility/phabricator · warning · PhutilArgumentUsageException

Specified "--limit" must be a positive integer.

Error message

Specified "--limit" must be a positive integer.

What it means

Thrown when `--limit` is provided to a worker management command but is not a positive integer after casting. The limit caps how many matching tasks the command affects; zero or negative limits are meaningless (and PHP casts non-numeric strings to 0), so the workflow validates it explicitly before executing the task queries.

Source

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

            pht(
              'Specified "--min-priority" may not be larger than '.
              'specified "--max-priority".'));
        }
      }
    }

    if (!$any_constraints) {
      throw new PhutilArgumentUsageException(
        pht(
          'Use constraint flags (like "--id" or "--class") to select which '.
          'tasks to affect. Use "--help" for a list of supported constraint '.
          'flags.'));
    }

    if ($limit !== null) {
      $limit = (int)$limit;
      if ($limit <= 0) {
        throw new PhutilArgumentUsageException(
          pht(
            'Specified "--limit" must be a positive integer.'));
      }
    }

    $active_query = new PhabricatorWorkerActiveTaskQuery();
    $archive_query = new PhabricatorWorkerArchiveTaskQuery();

    if ($ids) {
      $active_query = $active_query->withIDs($ids);
      $archive_query = $archive_query->withIDs($ids);
    }

    if ($class) {
      $class_array = array($class);
      $active_query = $active_query->withClassNames($class_array);
      $archive_query = $archive_query->withClassNames($class_array);
    }

View on GitHub (pinned to 5720a38cfe)

Solutions

Pass a positive integer such as `--limit 100`
Skip the flag entirely when no cap is wanted
In automation, omit `--limit` when the computed value would be <= 0 instead of passing it through

Example fix

# before
./bin/worker archive --limit 0 --class X

# after
./bin/worker archive --class X

Defensive patterns

Strategy: validation

Validate before calling

$args = array('./bin/worker', $subcommand);
if ($limit !== null) {
  $limit = (int)$limit;
  if ($limit <= 0) {
    unset($limit); // omit the flag rather than fail
  } else {
    $args[] = '--limit='.$limit;
  }
}

Prevention

Skip --limit when the computed cap is zero or negative instead of passing it
Validate numeric flags against a positive-int regex before building commands

When it happens

Trigger: `./bin/worker archive --limit 0 --class X`, `--limit -1`, or `--limit abc` (casts to 0). Fires only when the flag is present; omitting `--limit` entirely is fine.

Common situations: Scripts computing a limit from a counter that can legitimately be zero (empty result set upstream); shell variables that expand to empty; reusing a `--limit` value that was valid for pagination elsewhere but got decremented past zero.

Related errors

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