phacility/phabricator · error · PhutilArgumentUsageException

Select a user account to act on with "--user <username>".

Error message

Select a user account to act on with "--user <username>".

What it means

selectUser() in the shared PhabricatorPeopleManagementWorkflow base class requires a --user argument; every subcommand (approve, disable, enable, empower, ...) resolves its target through it. When the argument is absent or an empty string (strlen check), the workflow aborts with this PhutilArgumentUsageException before any query runs. It is purely a command-line usage error.

Source

Thrown at src/applications/people/management/PhabricatorPeopleManagementWorkflow.php:20

abstract class PhabricatorPeopleManagementWorkflow
  extends PhabricatorManagementWorkflow {

  final protected function getUserSelectionArguments() {
    return array(
      array(
        'name' => 'user',
        'param' => 'username',
        'help' => pht('User account to act on.'),
      ),
    );
  }

  final protected function selectUser(PhutilArgumentParser $argv) {
    $username = $argv->getArg('user');

    if (!strlen($username)) {
      throw new PhutilArgumentUsageException(
        pht(
          'Select a user account to act on with "--user <username>".'));
    }

    $user = id(new PhabricatorPeopleQuery())
      ->setViewer($this->getViewer())
      ->withUsernames(array($username))
      ->executeOne();
    if (!$user) {
      throw new PhutilArgumentUsageException(
        pht(
          'No user with username "%s" exists.',
          $username));
    }

    return $user;
  }

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add `--user <username>` to the command
2. Guard scripts with `[ -n "$USERNAME" ]` (or enable `set -u`) so empty values fail early with your own message
3. Run `./bin/people <command> --help` to confirm the expected arguments

Example fix

# before
./bin/people approve
# after
./bin/people approve --user alice

# bash: fail fast when the username is missing/empty
: "${USERNAME:?usage: --user <username> is required}"

When it happens

Trigger: Running `./bin/people approve` with no flags; passing an explicitly empty value like `--user ''`; shell scripts where the username variable is unset/unset-checked and expands to nothing.

Common situations: Scripts without `set -u` letting empty variables through; copy-pasted examples with the placeholder left in; CI jobs where the username parameter was never injected.

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

• User account "%s" is already approved. You can only approve
• User account "%s" is already an administrator. You can only
• User account "%s" is not disabled. You can only enable accou
• Request parameter "%s" is not formatted properly. Expected a
• Specify a public key to revoke trust for with --id.

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