phacility/phabricator · critical · Exception

Database "%s" is configured as a replica, but does not speci

Error message

Database "%s" is configured as a replica, but does not specify which "master" it follows in configuration. Valid masters are: %s.

What it means

In a partitioned setup (more than one entry with `role => 'master'`), every replica must say which master it follows via the `master` key. The parser can only auto-select a master when exactly one exists (`head($master_keys)`); with multiple masters an implicit choice is ambiguous, so any replica lacking an explicit `master` key throws this error listing the valid master ref keys (host:port strings).

Source

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

      }

      $server = $config[$key];

      $partition = idx($server, 'partition');
      if ($partition !== null) {
        throw new Exception(
          pht(
            'Database "%s" is configured as a replica, but specifies a '.
            '"partition". Only master databases may have a partition '.
            'configuration. Replicas use the same configuration as the '.
            'master they follow.',
            $ref->getRefKey()));
      }

      $master_key = idx($server, 'master');
      if ($master_key === null) {
        if ($is_partitioned) {
          throw new Exception(
            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])) {

View on GitHub (pinned to 5720a38cfe)

Solutions

Add a `master` key to the failing replica entry and set it to one of the ref keys listed in the message — these are `host:port` strings of the masters (e.g. `master1.example.com:3306`), not the config array keys.
Copy the value verbatim from the 'Valid masters are' list to avoid host/port mismatches.
Confirm the master entry itself has `role => 'master'` and a `partition` block, then re-parse.

Example fix

// before
'db-replica-a' => array(
  'host' => 'replica.example.com',
  'role' => 'replica',
),
// after (second master added, so partitioned mode)
'db-replica-a' => array(
  'host' => 'replica.example.com',
  'role' => 'replica',
  'master' => 'master1.example.com:3306',
),

Defensive patterns

Strategy: validation

Validate before calling

function assertReplicasHaveMaster(array $config) {
  $masters = 0;
  foreach ($config as $server) {
    if ($server['role'] === 'master') { $masters++; }
  }
  if ($masters < 2) { return; }
  foreach ($config as $key => $server) {
    if ($server['role'] !== 'master'
        && !strlen((string)idx($server, 'master'))) {
      throw new Exception(
        'Replica '.$key.' needs an explicit "master" in a partitioned cluster.');
    }
  }
}

Prevention

When adding a second master, audit every replica in the same change and add `master => host:port` to each.
Keep the master's host:port stable, or update referencing replicas atomically in the same config edit.
Remember the `master` value is a host:port ref key, not the config array key — encode that in your config template.

When it happens

Trigger: Adding a second master to a previously single-master cluster: pre-existing replica entries that never needed a `master` key now fail because `$is_partitioned` becomes true. Also hit when a new replica entry is written from old pre-partitioning documentation.

Common situations: Scaling out from one master to two partitioned masters without updating replicas; config migrated between installs; documentation drift after a Phabricator upgrade.

Related errors

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