phacility/phabricator · warning · PhutilArgumentUsageException

Identifier "%s" matches multiple users. Specify each user un

Error message

Identifier "%s" matches multiple users. Specify each user unambiguously with "@username" or by using user PHIDs.

What it means

A PhutilArgumentUsageException from the shared user-resolution helper: a single identifier matched more than one user because the notations overlap — the code comment gives the canonical case, a user literally named '25' plus a user with numeric ID 25, so '--user 25' is ambiguous. The helper refuses to guess; disambiguate with '@username' (forces username interpretation) or a user PHID.

Source

Thrown at src/infrastructure/management/PhabricatorManagementWorkflow.php:178

        $results[$id][] = $user;
      }
    }

    $list = array();
    foreach ($identifiers as $identifier) {
      $users = idx($results, $identifier, array());
      if (!$users) {
        throw new PhutilArgumentUsageException(
          pht(
            'No user "%s" exists. Specify users by username, ID, or PHID.',
            $identifier));
      }

      if (count($users) > 1) {
        // This can happen if you have a user "@25", a user with ID 25, and
        // specify "--user 25". You can disambiguate this by specifying
        // "--user @25".
        throw new PhutilArgumentUsageException(
          pht(
            'Identifier "%s" matches multiple users. Specify each user '.
            'unambiguously with "@username" or by using user PHIDs.',
            $identifier));
      }

      $list[] = head($users);
    }

    return $list;
  }

}

View on GitHub (pinned to 5720a38cfe)

Solutions

Prefix the identifier with '@' to force username matching: --user @25
Use the user's PHID, which is unambiguous: --user PHID-USER-xxxx
Long term, avoid purely numeric usernames so IDs and usernames cannot collide

Example fix

# before: matches user ID 25 AND user named "25"
$ bin/user edit --user 25 ...

# after: unambiguous forms
$ bin/user edit --user @25 ...
$ bin/user edit --user PHID-USER-xyzw1234 ...

Defensive patterns

Strategy: validation

Validate before calling

// Avoid ID/username collisions: always prefix usernames with '@'.
$identifiers = array_map(
  function ($id) {
    return preg_match('/^\d+$/', $id) ? "@{$id}" : $id;
  },
  $identifiers);

Try / catch

try { $list = $workflow->selectUsers($users, $identifiers); } catch (PhutilArgumentUsageException $ex) { /* on ambiguity message, re-run with @username or PHID forms */ }

Prevention

Never pass bare numbers when numeric usernames may exist; use @username or PHID-USER-... instead
Avoid creating purely numeric usernames when provisioning accounts

When it happens

Trigger: A numeric identifier that is simultaneously a valid user ID and a numeric username; occasionally an identifier matching a username case-insensitively and another field.

Common situations: Installs that auto-assigned numeric usernames ('25', '1089') colliding with user IDs; import scripts passing bare numbers for users whose usernames are also numeric.

Related errors

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