phacility/phabricator · warning · PhutilArgumentUsageException

You must specify the username of the account to recover.

Error message

You must specify the username of the account to recover.

What it means

The bin/auth recover workflow requires exactly one username as a wildcard argument. With no username supplied, getArg('username') is empty and the workflow aborts with a usage exception before any user lookup.

Source

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

      ->setArguments(
        array(
          array(
            '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));

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Run ./bin/auth recover <username> with the exact account username.
2. Optionally add --force-full-session when the recovery link must grant a full (not partial) session.
3. Check ./bin/auth help recover for the supported options.

Example fix

// before
./bin/auth recover
// after
./bin/auth recover alincoln

# guard the argument before invoking
[ "$#" -eq 1 ] || { echo 'usage: auth recover <username>' >&2; exit 2; }
./bin/auth recover "$1"

When it happens

Trigger: Running './bin/auth recover' with no arguments, or a wrapper script dropping the username parameter.

Common situations: Assuming the tool prompts for a username; copy-pasting an example command without substituting a real username; argument dropped in shell quoting mistakes.

Related errors

• You can only recover the username for one account.
• You must specify the path to a public keyfile with %s.
• You must specify the path to a pkcs8 keyfile with %s.
• No such user "%s" to recover.
• This account ("%s") can not establish web sessions, so it is

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