phacility/phabricator · error · PhutilArgumentUsageException

Expected a list of hints in JSON format: %s

Error message

Expected a list of hints in JSON format: %s

What it means

Thrown by `bin/repository hint` when `phutil_json_decode()` raises while parsing the stdin payload, i.e. the bytes read from stdin are not valid JSON. The message embeds the underlying decoder error (unexpected token, unterminated string, trailing commas, etc.). It aborts before any hint is written to the `repository_commit_hint` table.

Source

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

      ->setArguments(array());
  }

  public function execute(PhutilArgumentParser $args) {
    $viewer = $this->getViewer();

    echo tsprintf(
      "%s\n",
      pht('Reading list of hints from stdin...'));

    $hints = file_get_contents('php://stdin');
    if ($hints === false) {
      throw new PhutilArgumentUsageException(pht('Failed to read stdin.'));
    }

    try {
      $hints = phutil_json_decode($hints);
    } catch (Exception $ex) {
      throw new PhutilArgumentUsageException(
        pht(
          'Expected a list of hints in JSON format: %s',
          $ex->getMessage()));
    }

    $repositories = array();
    foreach ($hints as $idx => $hint) {
      if (!is_array($hint)) {
        throw new PhutilArgumentUsageException(
          pht(
            'Each item in the list of hints should be a JSON object, but '.
            'the item at index "%s" is not.',
            $idx));
      }

      try {
        PhutilTypeSpec::checkMap(
          $hint,

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Validate before piping: `php -r 'exit(json_decode(file_get_contents("hints.json")) === null ? 1 : 0);' && ./bin/repository hint < hints.json`.
2. Re-save the file as UTF-8 without BOM and remove trailing commas / comments.
3. Regenerate the JSON with `json_encode` (PHP) or `jq -c . hints.json > clean.json` to normalize it.
4. Read the embedded decoder message in the exception — it names the exact byte offset of the syntax error.

Example fix

// before
$ echo "hints for old sha" | ./bin/repository hint
[1161] Expected a list of hints in JSON format: Syntax error

// after
$ cat > hints.json <<'EOF'
[{"repository":"R1","old":"deadbeef","hint":"obsolete ref"}]
EOF
$ ./bin/repository hint < hints.json

php -r '$d = json_decode(file_get_contents($argv[1]), true); if (json_last_error() !== JSON_ERROR_NONE) { fwrite(STDERR, json_last_error_msg()."\n"); exit(1); }' hints.json && ./bin/repository hint < hints.json

When it happens

Trigger: Piping a bare string or shell-quoted text instead of JSON (`echo 'cleanup' | ./bin/repository hint`); JSON with trailing commas, single-quoted keys, or unescaped newlines; a truncated file (transfer cut off, or `head` used on it); an empty stdin read as '' which json_decode rejects; BOM-prefixed JSON saved from a Windows editor.

Common situations: Hand-writing the hints file and forgetting array brackets; generating it with string interpolation that breaks quoting (`echo "[{old: $sha}]"`); files edited on Windows with a BOM; piping through a command that emits a warning line before the JSON.

Related errors

• Each item in the list of hints should be a JSON object, but
• Failed to read stdin.
• Unexpected hint format at index "%s": %s
• Request parameter "%s" is not formatted properly. Expected a
• Request parameter "%s" is not formatted properly. Expected a

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