phacility/phabricator · error · PhutilArgumentUsageException

Repository identifier "%s" (in hint at index "%s") does not

Error message

Repository identifier "%s" (in hint at index "%s") does not identify a valid repository.

What it means

Thrown by `bin/repository hint` when `PhabricatorRepositoryQuery->withIdentifiers([...])->executeOne()` returns no result for a hint's `repository` value. The identifier may be a repository ID (int) or callsign (string); if neither matches a visible repository, processing stops before `PhabricatorRepositoryCommitHint::updateHint()` is called. Note the query runs with the acting viewer, so permission filtering also applies.

Source

Thrown at src/applications/repository/management/PhabricatorRepositoryManagementHintWorkflow.php:72

            'hint' => 'string',
          ));
      } catch (Exception $ex) {
        throw new PhutilArgumentUsageException(
          pht(
            'Unexpected hint format at index "%s": %s',
            $idx,
            $ex->getMessage()));
      }

      $repository_identifier = $hint['repository'];
      $repository = idx($repositories, $repository_identifier);
      if (!$repository) {
        $repository = id(new PhabricatorRepositoryQuery())
          ->setViewer($viewer)
          ->withIdentifiers(array($repository_identifier))
          ->executeOne();
        if (!$repository) {
          throw new PhutilArgumentUsageException(
            pht(
              'Repository identifier "%s" (in hint at index "%s") does not '.
              'identify a valid repository.',
              $repository_identifier,
              $idx));
        }

        $repositories[$repository_identifier] = $repository;
      }

      PhabricatorRepositoryCommitHint::updateHint(
        $repository->getPHID(),
        $hint['old'],
        idx($hint, 'new'),
        $hint['hint']);

      echo tsprintf(
        "%s\n",

View on GitHub (pinned to 5720a38cfe)

Solutions

Correct the identifier: use the repository callsign (e.g. `R123`) or numeric ID exactly as shown in Diffusion.
Cross-check it exists: open Diffusion → the repository, or run `./bin/repository list`.
If generating hints programmatically, resolve callsigns via `PhabricatorRepositoryQuery` before writing the file.
Run the command as an administrative user (e.g. `./bin/repository hint` under the phabricator ops user, or with `--actor`) so policy filtering does not hide the repository.

Example fix

// before
[{"repository":"RR1","old":"deadbeef","hint":"obsolete"}]
// RR1 is a typo -> [1164] Repository identifier "RR1" ... does not identify a valid repository.

// after
[{"repository":"R1","old":"deadbeef","hint":"obsolete"}]

Defensive patterns

Strategy: validation

Validate before calling

# Confirm the callsign resolves before running the hint import:
./bin/repository list | grep -w R1 || { echo 'unknown repository R1' >&2; exit 1; }
./bin/repository hint < hints.json

Type guard

function resolve_repository($viewer, $identifier) {
  return id(new PhabricatorRepositoryQuery())
    ->setViewer($viewer)
    ->withIdentifiers(array($identifier))
    ->executeOne(); // null => would trigger [1164]; check before updateHint()
}

Prevention

Use callsigns exactly as shown in Diffusion (R + letters), not PHIDs or remote URLs.
When hints come from another instance, map callsigns through a lookup table rather than trusting the old names.
Run as an admin/ops user so policy filtering cannot hide the repository from withIdentifiers().

When it happens

Trigger: A callsign typo (`RR1` instead of `R1`); using the PHID (e.g. `PHID-REPO-xyz`) which withIdentifiers may not resolve; a numeric string ID for a deleted repository; running the workflow as a system/daemon user whose viewer cannot see the repository (policy filtering); identifier correct but repository row soft-deleted.

Common situations: Hint files generated from an older Phabricator instance after repositories were renamed or re-created; scripts copy the Git remote URL instead of the Phabricator callsign into `repository`; running via sudo with a different acting user that lacks visibility.

Related errors

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