phacility/phabricator · error · PhutilArgumentUsageException

Configuration file specifies cluster peer "%s" more than onc

Error message

Configuration file specifies cluster peer "%s" more than once (at indexes "%s" and "%s"). Each peer must have a unique host and port combination.

What it means

Thrown when two entries in the 'cluster' section of the Aphlict config produce the same host:port peer key. Each peer must identify a distinct node endpoint; duplicates usually mean the same node was listed twice.

Source

Thrown at src/applications/aphlict/management/PhabricatorAphlictManagementWorkflow.php:262

          break;
        default:
          throw new PhutilArgumentUsageException(
            pht(
              'Configuration file specifies cluster peer ("%s", at index '.
              '"%s") with an invalid protocol, "%s". Valid protocols are '.
              '"%s" or "%s".',
              $host,
              $index,
              $protocol,
              'http',
              'https'));
      }

      $peer_key = "{$host}:{$port}";
      if (!isset($peer_map[$peer_key])) {
        $peer_map[$peer_key] = $index;
      } else {
        throw new PhutilArgumentUsageException(
          pht(
            'Configuration file specifies cluster peer "%s" more than '.
            'once (at indexes "%s" and "%s"). Each peer must have a '.
            'unique host and port combination.',
            $peer_key,
            $peer_map[$peer_key],
            $index));
      }
    }

    $this->configData = $data;
    $this->configPath = $full_path;

    $pid_path = $this->getPIDPath();
    try {
      $dir = dirname($pid_path);
      if (!Filesystem::pathExists($dir)) {
        Filesystem::createDirectory($dir, 0755, true);

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Deduplicate cluster entries so each host:port pair appears exactly once
2. List every OTHER node of the cluster on each node's config (this node itself does not need to be its own peer)

Example fix

// before
"cluster": [
  {"host": "node2", "port": 22281, "protocol": "http"},
  {"host": "node2", "port": 22281, "protocol": "http"}
]
// after
"cluster": [
  {"host": "node2", "port": 22281, "protocol": "http"}
]

$seen = array();
foreach (idx($config, 'cluster', array()) as $peer) {
  $k = $peer['host'].':'.$peer['port'];
  if (isset($seen[$k])) {
    throw new InvalidArgumentException("Duplicate cluster peer {$k}");
  }
  $seen[$k] = true;
}

When it happens

Trigger: The cluster list contains two entries with identical host and port (exact same node listed twice), or one host listed twice where the port was not actually changed in the second entry.

Common situations: Copy-pasting a peer entry to add a third node and editing only the host (port left identical on the same host); merging cluster configs from two nodes that each listed the same bootstrap peer.

Related errors

• Configuration file specifies cluster peer ("%s", at index "%
• Configuration file is not properly formatted JSON. %s
• Configuration file has improper configuration keys at top le
• Two servers (at indexes "%s" and "%s") both bind to the same
• A specified server (at index "%s", on port "%s") has an inva

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