phacility/phabricator · warning · PhutilArgumentUsageException

Use constraint flags (like "--id" or "--class") to select wh

Error message

Use constraint flags (like "--id" or "--class") to select which tasks to affect. Use "--help" for a list of supported constraint flags.

What it means

Thrown when a `bin/worker` management subcommand is invoked with no task-selection constraint at all. Because these commands mutate tasks (retry, archive, reprioritize, etc.), Phabricator requires at least one of `--id`, `--class`, `--active`/`--archived`, `--min-failures`/`--max-failures`, `--min-priority`/`--max-priority`, `--object`, `--container`, or `--limit`-adjacent constraints, so an accidental 'affect everything' invocation cannot happen. The check counts any constraint flag before running the query.

Source

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

              '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".'));
        }
      }
    }

    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();

View on GitHub (pinned to 5720a38cfe)

Solutions

Add at least one constraint, e.g. `--class PhabricatorMailWorker` or `--id 123`
Run `./bin/worker <command> --help` to list the supported constraint flags
Intentionally target everything with the broad constraint pair `--active --archived` minus the conflicting one, e.g. run twice with `--active` then `--archived` plus `--class`

Example fix

# before
./bin/worker retry

# after
./bin/worker retry --class PhabricatorWorkerBulkJobWorker --active

Defensive patterns

Strategy: validation

Validate before calling

$constraintFlags = array_filter(array(
  '--id' => $ids, '--class' => $class,
  '--active' => $active, '--archived' => $archived,
));
if (empty($constraintFlags)) {
  fwrite(STDERR, "Refusing to run a worker command with no constraints.\n");
  exit(1);
}

Prevention

Always author worker mutation commands with an explicit scope; never rely on a default
Dry-run selection with `bin/worker show` constraints before mutation commands in automation

When it happens

Trigger: Bare invocations like `./bin/worker retry`, `./bin/worker archive`, or `./bin/worker priority --priority 1000` with no selector. Note that `--priority` and `--limit` alone do not count as constraints.

Common situations: Operators expecting an interactive prompt or a default scope; scripts whose constraint variables expand to empty strings; running the command expecting `--help` output; forgetting that mutation commands never default to 'all tasks'.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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