phacility/phabricator · error · Exception

This server is not configured to serve cluster requests. Set

Error message

This server is not configured to serve cluster requests. Set `cluster.addresses` in the configuration to whitelist cluster hosts before sending requests that use a cluster authentication mechanism.

What it means

PhabricatorEnv::isClusterAddress($address) checks an address against the `cluster.addresses` CIDR whitelist via PhutilCIDRList. If that config is empty, there is no whitelist to test against, yet the caller is attempting a cluster-auth decision (e.g. verifying a request signed with a cluster token). Phabricator throws rather than returning false-with-no-config, forcing the operator to make the cluster boundary explicit - an unconfigured cluster must never silently authorize or under-authorize cluster traffic.

Source

Thrown at src/infrastructure/env/PhabricatorEnv.php:885

    if (!$cluster_addresses) {
      return false;
    }

    $address = self::getRemoteAddress();
    if (!$address) {
      throw new Exception(
        pht(
          'Unable to test remote address against cluster whitelist: '.
          'REMOTE_ADDR is not defined or not valid.'));
    }

    return self::isClusterAddress($address);
  }

  public static function isClusterAddress($address) {
    $cluster_addresses = self::getEnvConfig('cluster.addresses');
    if (!$cluster_addresses) {
      throw new Exception(
        pht(
          'This server is not configured to serve cluster requests. '.
          'Set `cluster.addresses` in the configuration to whitelist '.
          'cluster hosts before sending requests that use a cluster '.
          'authentication mechanism.'));
    }

    return PhutilCIDRList::newList($cluster_addresses)
      ->containsAddress($address);
  }

  public static function getRemoteAddress() {
    $address = idx($_SERVER, 'REMOTE_ADDR');
    if (!$address) {
      return null;
    }

    try {

View on GitHub (pinned to 5720a38cfe)

Solutions

Define the whitelist on every node: `./bin/config set cluster.addresses '["10.0.0.0/24"]'` listing CIDRs covering all nodes' addresses as seen by each peer.
Verify each node sees the config: `./bin/config get cluster.addresses` per host; ensure config distribution (same local.json, same config pipeline) across the fleet.
If this install is genuinely single-node, stop sending cluster-authenticated requests to it (check the upstream node's configuration that is signing requests).

Example fix

# before: node receives cluster-authed request with no whitelist
Exception: This server is not configured to serve cluster requests...

# after: define the cluster CIDR on every node
$ ./bin/config set cluster.addresses '["10.0.0.0/24"]'
$ ./bin/phd restart

Defensive patterns

Strategy: validation

Validate before calling

if (!PhabricatorEnv::getEnvConfig('cluster.addresses')) {
  throw new Exception(
    'cluster.addresses must be configured before accepting cluster traffic.');
}

Try / catch

try {
  $ok = PhabricatorEnv::isClusterAddress($address);
} catch (Exception $ex) {
  // unconfigured cluster boundary: refuse cluster auth entirely
  $ok = false;
  phlog(pht('Cluster request rejected: %s', $ex->getMessage()));
}

Prevention

Distribute identical cluster.addresses to every node via config management; drift here breaks auth.
Add a deploy pre-flight asserting the key is non-empty on all nodes of a clustered install.
Decide the cluster boundary (CIDR list) once and treat edits like firewall changes.

When it happens

Trigger: A node receives a request using a cluster authentication mechanism (request signed by another node's cluster token, or any call to isClusterAddress()) while `cluster.addresses` is unset/empty - common when web nodes were cloned and one instance's config lacks the key.

Common situations: Scaling out from single-node to multi-node and forgetting to distribute cluster.addresses to every node; removing the config on one host during troubleshooting while the LB still routes cluster-authed traffic to it; git-based config drift across the fleet.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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