What causes "You can only recover the username for one account." in phacility/phabricator?

Recover accounts one at a time: ./bin/auth recover alice, then ./bin/auth recover bob.

phacility/phabricator · warning · PhutilArgumentUsageException

You can only recover the username for one account.

Error message

You can only recover the username for one account.

What it means

The username argument is a wildcard, so PhutilArgumentParser accepts several values syntactically, but account recovery is strictly per-account: count($usernames) > 1 aborts with PhutilArgumentUsageException and no recovery link is generated for any of them.

Source

Thrown at src/applications/auth/management/PhabricatorAuthManagementRecoverWorkflow.php:34

            'name' => 'force-full-session',
            'help' => pht(
              'Recover directly into a full session without requiring MFA '.
              'or other login checks.'),
          ),
          array(
            'name' => 'username',
            'wildcard' => true,
          ),
        ));
  }

  public function execute(PhutilArgumentParser $args) {
    $usernames = $args->getArg('username');
    if (!$usernames) {
      throw new PhutilArgumentUsageException(
        pht('You must specify the username of the account to recover.'));
    } else if (count($usernames) > 1) {
      throw new PhutilArgumentUsageException(
        pht('You can only recover the username for one account.'));
    }

    $username = head($usernames);

    $user = id(new PhabricatorPeopleQuery())
      ->setViewer($this->getViewer())
      ->withUsernames(array($username))
      ->executeOne();

    if (!$user) {
      throw new PhutilArgumentUsageException(
        pht(
          'No such user "%s" to recover.',
          $username));
    }

    if (!$user->canEstablishWebSessions()) {

View on GitHub (pinned to 5720a38cfe)

Solutions

Recover accounts one at a time: ./bin/auth recover alice, then ./bin/auth recover bob.
For several accounts, loop in the shell: for u in alice bob; do ./bin/auth recover "$u"; done

Example fix

// before
./bin/auth recover alice bob
// after
for u in alice bob; do ./bin/auth recover "$u"; done

Defensive patterns

Strategy: validation

Validate before calling

# guard: exactly one account per invocation
[ "$#" -eq 1 ] || { echo 'one username at a time' >&2; exit 2; }
./bin/auth recover "$1"

Prevention

Recovery is per-account; loop over usernames instead of passing several.
Do not paste space-separated lists into a single command.
Check argument count in wrapper scripts.

When it happens

Trigger: Running './bin/auth recover alice bob' (two or more usernames) in one invocation.

Common situations: Bulk-recovering several locked-out users at once; paste lists into the command line assuming batch behavior.

Related errors

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