phacility/phabricator · warning · PhutilArgumentUsageException

This server is configured in cluster mode, with multiple dat

Error message

This server is configured in cluster mode, with multiple database hosts. Use "--host" to specify which host you want to operate on.

What it means

PhabricatorStorageManagementWorkflow::getSingleAPI() requires exactly one database API but got several: this install resolves to multiple database hosts (cluster mode). Single-host operations — such as `renamespace --live`, which dumps one specific database — refuse to guess which host you mean and demand `--host`.

Source

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

    }

    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.'));
  }

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

  final protected function isDryRun() {
    return $this->dryRun;
  }

  final protected function setDryRun($dry_run) {
    $this->dryRun = $dry_run;
    return $this;
  }

View on GitHub (pinned to 5720a38cfe)

Solutions

Add `--host <ref-key>` naming the exact database host to operate on.
List available hosts with `./bin/storage status` or read the ref keys from the cluster configuration.
For renamespace specifically, skip --live: mysqldump the host yourself and pass `--input <dump>` — the --input path never selects a host.

Example fix

# before
./bin/storage renamespace --live --from a --to b --output out.sql

# after
./bin/storage renamespace --live --host db-master-01 --from a --to b --output out.sql

Defensive patterns

Strategy: validation

Validate before calling

[ -n "$HOST" ] || { echo 'error: set HOST (--host) for cluster installs' >&2; exit 2; }
./bin/storage renamespace --live --host "$HOST" --from "$FROM" --to "$TO"

Prevention

Always pass --host on installs with more than one database ref.
Prefer the --input path (dump the host yourself) for scripted renamespace runs.

When it happens

Trigger: Running a workflow that calls getSingleAPI() (for example renamespace with `--live`) on an install with multiple database refs configured, without passing `--host`, so count($apis) != 1.

Common situations: First use of renamespace --live on a clustered production install; adding a replica to the configuration and forgetting that single-host commands now need --host.

Related errors

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