phacility/phabricator · error · PhutilArgumentUsageException

Configuration file specifies cluster peer ("%s", at index "%

Error message

Configuration file specifies cluster peer ("%s", at index "%s") with an invalid protocol, "%s". Valid protocols are "%s" or "%s".

What it means

Thrown while validating the 'cluster' section of the Aphlict config when a cluster peer's 'protocol' field is not the string 'http' or 'https'. Peers describe the other Aphlict nodes in a notification cluster, and each is addressed over HTTP(S) for intra-cluster message replication.

Source

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

    foreach ($cluster as $index => $peer) {
      PhutilTypeSpec::checkMap(
        $peer,
        array(
          'host' => 'string',
          'port' => 'int',
          'protocol' => 'string',
        ));

      $host = $peer['host'];
      $port = $peer['port'];
      $protocol = $peer['protocol'];

      switch ($protocol) {
        case 'http':
        case 'https':
          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 '.

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Set each cluster peer's "protocol" to "http" (or "https" when peers talk over TLS)
2. For https peers, make sure the target admin listener actually has ssl.key/ssl.cert configured

Example fix

// before
"cluster": [{"host": "aphlict-2", "port": 22281, "protocol": "ws"}]
// after
"cluster": [{"host": "aphlict-2", "port": 22281, "protocol": "https"}]

foreach (idx($config, 'cluster', array()) as $peer) {
  if (!in_array(idx($peer, 'protocol'), array('http', 'https'), true)) {
    throw new InvalidArgumentException('Cluster protocol must be http or https');
  }
}

function is_valid_peer_protocol($protocol) {
  return is_string($protocol)
    && in_array(strtolower($protocol), array('http','https'), true);
}

When it happens

Trigger: A cluster entry like {"host": "aphlict2.example.com", "port": 22281, "protocol": "ws"} or "tcp", or a null/missing-then-defaulted protocol value.

Common situations: Admins reuse websocket-style URLs from the client server docs for peer entries; config migrated from a template where protocol was left blank.

Related errors

• Configuration file specifies cluster peer "%s" more than onc
• 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/ffdc2ced9a9a4713. Report an issue: GitHub.