What causes "Priority must be a positive integer." in phacility/phabricator?

Re-run with a positive integer, e.g. `./bin/worker priority --priority 1000 --id 42`

phacility/phabricator · warning · PhutilArgumentUsageException

Priority must be a positive integer.

Error message

Priority must be a positive integer.

What it means

Thrown by the `bin/worker priority` management workflow (PhabricatorWorkerManagementPriorityWorkflow) when the value passed via `--priority` is not a positive integer. The command casts the argument to int and rejects anything <= 0 because task priority is stored as an unsigned value; zero or negative priorities would be meaningless for worker queue ordering. It is a PhutilArgumentUsageException, meaning the CLI invocation itself is malformed, not that any task failed.

Source

Thrown at src/infrastructure/daemon/workers/management/PhabricatorWorkerManagementPriorityWorkflow.php:39

                'Set tasks to this priority. Tasks with a smaller priority '.
                'value execute before tasks with a larger priority value.'),
            ),
          ),
          $this->getTaskSelectionArguments()));
  }

  public function execute(PhutilArgumentParser $args) {
    $new_priority = $args->getArg('priority');

    if ($new_priority === null) {
      throw new PhutilArgumentUsageException(
        pht(
          'Select a new priority for selected tasks with "--priority".'));
    }

    $new_priority = (int)$new_priority;
    if ($new_priority <= 0) {
      throw new PhutilArgumentUsageException(
        pht(
          'Priority must be a positive integer.'));
    }

    $tasks = $this->loadTasks($args);

    if (!$tasks) {
      $this->logWarn(
        pht('NO TASKS'),
        pht('No tasks selected to reprioritize.'));

      return 0;
    }

    $priority_count = 0;
    foreach ($tasks as $task) {
      $can_reprioritize = !$task->isArchived();
      if (!$can_reprioritize) {

View on GitHub (pinned to 5720a38cfe)

Solutions

Re-run with a positive integer, e.g. `./bin/worker priority --priority 1000 --id 42`
If the value comes from a script, clamp/validate it before invoking the CLI: reject or default values <= 0
Check the exact spelling of the flag (`--priority`) and that its value is numeric, not empty or alphabetic

Example fix

# before
./bin/worker priority --priority 0 --id 42

# after
./bin/worker priority --priority 1000 --id 42

Defensive patterns

Strategy: validation

Validate before calling

// before shelling out to bin/worker priority
$newPriority = (int)$configured_priority;
if ($new_priority <= 0) {
  throw new InvalidArgumentException(
    '--priority must be a positive integer, got: '.$configured_priority);
}
exec(sprintf(
  './bin/worker priority --priority %d --id %d',
  $new_priority,
  $task_id,
));

Prevention

Treat priority as unsigned in any script that computes it; clamp or reject <= 0 before invoking the CLI
Never pass shell variables unquoted or unexpanded-empty into --priority
Run `./bin/worker priority --help` once in CI for scripts to pin the expected flag surface

When it happens

Trigger: Running `./bin/worker priority --priority 0 --id 123`, `--priority -5`, or a non-numeric value like `--priority abc` (PHP's `(int)` cast turns it into 0). Also triggered by omitting a usable value after the flag is parsed as an empty string. Requires `--priority` to be non-null first (a null value throws the separate 'Select a new priority' error).

Common situations: Automation scripts that compute a priority from another variable which can be 0 or negative; shell scripts passing an unset environment variable that expands to empty; typos like `--priority=O` (letter O). Common when operators retask queues during incident response and pass a computed value without validating it.

Related errors

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