phacility/phabricator · error · Exception

Search cluster configuration has an invalid host specificati

Error message

Search cluster configuration has an invalid host specification (at index "%s"): %s.

What it means

Each entry in a service's `hosts` list is checked with PhutilTypeSpec::checkMap and must be a map with a required `host` string plus optional roles (map), port (int), protocol (string), path (string), version (int). Unknown keys, a missing `host` key, or wrong value types raise this error, tagged with the index of the failing host inside `hosts` and the underlying check detail.

Source

Thrown at src/infrastructure/cluster/config/PhabricatorClusterSearchConfigType.php:70

            $spec['type'],
            implode(', ', array_keys($engines))));
      }

      if (isset($spec['hosts'])) {
        foreach ($spec['hosts'] as $hostindex => $host) {
          try {
            PhutilTypeSpec::checkMap(
              $host,
              array(
                'host'     => 'string',
                'roles'     => 'optional map<string, wild>',
                'port'      => 'optional int',
                'protocol'  => 'optional string',
                'path'      => 'optional string',
                'version'   => 'optional int',
              ));
          } catch (Exception $ex) {
            throw new Exception(
              pht(
                'Search cluster configuration has an invalid host '.
                'specification (at index "%s"): %s.',
                $hostindex,
                $ex->getMessage()));
          }
        }
      }
    }
  }
}

View on GitHub (pinned to 5720a38cfe)

Solutions

Wrap each host as `array('host' => 'es1.example.com', 'port' => 9200)`.
Keep only host/roles/port/protocol/path/version keys in host entries; delete anything else.
Ensure `port` and `version` are unquoted integers and every host map has a `host` string.

Example fix

// before
'hosts' => array('es1.example.com', 'es2.example.com'),
// after
'hosts' => array(
  array('host' => 'es1.example.com', 'port' => 9200),
  array('host' => 'es2.example.com', 'port' => 9200),
),

Defensive patterns

Strategy: validation

Validate before calling

$host_schema = array(
  'host'     => 'string',
  'roles'    => 'optional map<string, wild>',
  'port'     => 'optional int',
  'protocol' => 'optional string',
  'path'     => 'optional string',
  'version'  => 'optional int',
);
foreach ($spec['hosts'] as $host) {
  PhutilTypeSpec::checkMap($host, $host_schema);
}

Type guard

function isSearchHostSpec($host) {
  return is_array($host)
    && isset($host['host']) && is_string($host['host'])
    && (!isset($host['port']) || is_int($host['port']));
}

Prevention

Always wrap hostnames: `array('host' => 'es1', 'port' => 9200)`, never a bare string.
Only the six host keys are allowed — put cluster-wide options at the service level, not on hosts.
Use the UI's Add Host flow once and copy its output as the canonical template.

When it happens

Trigger: A host entry like `array('es1.example.com')` (bare string), `array('hosts' => 'es1.example.com')` (wrong nesting), omitting the required `host` key, or adding unsupported keys like `user` or `scheme`. Also `port` passed as a quoted string.

Common situations: Pasting hostnames as strings instead of dictionaries; confusing the service-level and host-level schemas; converting a URL like `http://es1:9200/idx` into fields incorrectly.

Related errors

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