phacility/phabricator · error · PhutilArgumentUsageException

This command only operates on database masters, but the sele

Error message

This command only operates on database masters, but the selected database hosts do not include any masters.

What it means

PhabricatorStorageManagementWorkflow::getMasterAPIs() found no master among the selected database hosts. Writing storage workflows (upgrade, destroy, adjust) operate only on masters; when every selected ref is a replica — or no ref is configured as master — the command aborts with this usage exception before touching anything.

Source

Thrown at src/infrastructure/storage/management/workflow/PhabricatorStorageManagementWorkflow.php:33

    return $this;
  }

  final public function getAnyAPI() {
    return head($this->getAPIs());
  }

  final public function getMasterAPIs() {
    $apis = $this->getAPIs();

    $results = array();
    foreach ($apis as $api) {
      if ($api->getRef()->getIsMaster()) {
        $results[] = $api;
      }
    }

    if (!$results) {
      throw new PhutilArgumentUsageException(
        pht(
          'This command only operates on database masters, but the selected '.
          'database hosts do not include any masters.'));
    }

    return $results;
  }

  final public function getSingleAPI() {
    $apis = $this->getAPIs();
    if (count($apis) == 1) {
      return head($apis);
    }

    throw new PhutilArgumentUsageException(
      pht(
        'This server is configured in cluster mode, with multiple database '.
        'hosts. Use "--host" to specify which host you want to operate on.'));

View on GitHub (pinned to 5720a38cfe)

Solutions

Pass `--host <ref-key>` naming a host whose role is master.
Review the cluster database configuration and make sure the intended server has role master (fix typos, uncomment entries).
Run `./bin/storage status` to see which hosts and roles the tool resolves.
After a promotion or failover, update the role configuration before running storage commands.

Defensive patterns

Strategy: validation

Validate before calling

// before invoking a writing workflow, confirm a master is selectable
$apis = $workflow->getAPIs();
$has_master = false;
foreach ($apis as $api) {
  if ($api->getRef()->getIsMaster()) {
    $has_master = true;
  }
}
if (!$has_master) {
  throw new Exception('no master host selected; pass --host or fix roles');
}

Prevention

Keep cluster role configuration in review scope; a typo'd role silently removes the master.
Run ./bin/storage status after any cluster config change to confirm roles resolve.

When it happens

Trigger: Cluster database configuration where every selected host has role replica: `--host` pointed at a replica, or the master entry missing or its role misspelled in the cluster database configuration, so the $results array stays empty.

Common situations: Pointing --host at the read-replica hostname; a cluster config where the master block is commented out or role is typo'd; running soon after a failover without updating roles; single-host installs accidentally configured with role replica.

Related errors

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