phacility/phabricator · critical · Exception

Database "%s" is configured as a replica and specifies a mas

Error message

Database "%s" is configured as a replica and specifies a master ("%s"), but that master is not a valid master. Valid masters are: %s.

What it means

A replica names its master with the `master` key, but that value does not resolve to a ref in the map the parser built. Ref keys are `host:port` strings (see PhabricatorDatabaseRef::getRefKey), so the `master` value must exactly match a configured master's host and port — pointing it at a config array key or a bare hostname fails.

Source

Thrown at src/infrastructure/cluster/PhabricatorDatabaseRefParser.php:203

            pht(
              'Database "%s" is configured as a replica, but does not '.
              'specify which "master" it follows in configuration. Valid '.
              'masters are: %s.',
              $ref->getRefKey(),
              implode(', ', $master_keys)));
        } else if ($master_keys) {
          $master_key = head($master_keys);
        } else {
          throw new Exception(
            pht(
              'Database "%s" is configured as a replica, but there is no '.
              'master configured.',
              $ref->getRefKey()));
        }
      }

      if (!isset($ref_map[$master_key])) {
        throw new Exception(
          pht(
            'Database "%s" is configured as a replica and specifies a '.
            'master ("%s"), but that master is not a valid master. Valid '.
            'masters are: %s.',
            $ref->getRefKey(),
            $master_key,
            implode(', ', $master_keys)));
      }

      $master_ref = $ref_map[$master_key];
      $ref->setMasterRef($ref_map[$master_key]);
      $master_ref->addReplicaRef($ref);
    }

    return array_values($refs);
  }

}

View on GitHub (pinned to 5720a38cfe)

Solutions

Set the replica's `master` value to one of the ref keys listed in the message's 'Valid masters are' list, verbatim (format `host:port`, e.g. `db1.example.com:3306`).
If the master uses a non-default port, include it in both the master's `port` and the replica's `master` value.
Re-run `bin/config get cluster.database` to confirm the strings match exactly (case, port, punctuation).

Example fix

// before
'db-replica-a' => array(
  'host' => 'replica.example.com',
  'role' => 'replica',
  'master' => 'db-master-a',
),
// after (master value is the master's host:port ref key)
'db-replica-a' => array(
  'host' => 'replica.example.com',
  'role' => 'replica',
  'master' => 'master.example.com:3306',
),

Defensive patterns

Strategy: validation

Validate before calling

function assertReplicaMasterKeysValid(array $config) {
  $master_keys = array();
  foreach ($config as $key => $server) {
    if ($server['role'] === 'master') {
      $ref = idx($server, 'port')
        ? $server['host'].':'.$server['port']
        : $server['host'];
      $master_keys[$ref] = true;
    }
  }
  foreach ($config as $key => $server) {
    if ($server['role'] === 'master') { continue; }
    $master = idx($server, 'master');
    if ($master !== null && empty($master_keys[$master])) {
      throw new Exception(
        'Replica '.$key.' names unknown master "'.$master.'". '.
        'Valid: '.implode(', ', array_keys($master_keys)));
    }
  }
}

Prevention

Treat `master` values as host:port ref keys — generate them from the master entry's host/port fields rather than hand-typing.
When renaming a master host or changing its port, grep cluster.database for the old ref key and update every replica in the same change.
Keep an install-wide inventory mapping replica → master ref key so audits are mechanical.

When it happens

Trigger: `master` in a replica entry is a typo'd host:port, uses the config array key instead of the host:port ref key, omits the port when the master sets a non-default one, or references another replica rather than a master.

Common situations: Renaming hosts or moving the master to a new port and forgetting dependent replicas; assuming `master` takes the array key from the config example; copy-paste between environments with different hostnames.

Related errors

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