phacility/phabricator · critical · PhabricatorClusterImpossibleWriteException

Unable to connect to master database ("%s"). This is a sever

Error message

Unable to connect to master database ("%s"). This is a severe failure; your request did not complete.

What it means

A write-mode connection is required, but no configured master could be contacted — every master attempt raised an exception, so raiseImpossibleWrite() throws PhabricatorClusterImpossibleWriteException and the message states plainly that the request did not complete. This is the severe end of the cluster exceptions: distinct from read-only refusal (1497) and from nothing-configured (1499); here masters exist in configuration but are all unreachable.

Source

Thrown at src/infrastructure/storage/lisk/PhabricatorLiskDAO.php:147

    if (!$master && !$replica) {
      $this->raiseUnconfigured($database);
    }

    $this->raiseUnreachable($database, $master_exception);
  }

  private function raiseImproperWrite($database) {
    throw new PhabricatorClusterImproperWriteException(
      pht(
        'Unable to establish a write-mode connection (to application '.
        'database "%s") because this server is in read-only mode. Whatever '.
        'you are trying to do does not function correctly in read-only mode.',
        $database));
  }

  private function raiseImpossibleWrite($database) {
    throw new PhabricatorClusterImpossibleWriteException(
      pht(
        'Unable to connect to master database ("%s"). This is a severe '.
        'failure; your request did not complete.',
        $database));
  }

  private function raiseUnconfigured($database) {
    throw new Exception(
      pht(
        'Unable to establish a connection to any database host '.
        '(while trying "%s"). No masters or replicas are configured.',
        $database));
  }

  private function raiseUnreachable($database, Exception $proxy = null) {
    $message = pht(
      'Unable to establish a connection to any database host '.
      '(while trying "%s"). All masters and replicas are completely '.

View on GitHub (pinned to 5720a38cfe)

Solutions

Restore reachability of at least one master: verify from the app host with mysql -h<master> and check mysqld/network on the master side
Fix the cluster database configuration (cluster.databases / mysql.host) if it points at the wrong host or uses bad credentials
Verify recovery with phabricator/bin/storage probe before letting traffic retry
If the master is genuinely lost, promote a replica to master and update configuration — during the gap, expect writes to keep failing with this exception

Defensive patterns

Strategy: retry

Validate before calling

// Health gate before retrying writes after an outage:
// phabricator/bin/storage probe   -> all configured masters must answer
// Only then resume write traffic.

Try / catch

try {
  $conn = $dao->establishConnection('w');
} catch (PhabricatorClusterImpossibleWriteException $ex) {
  // All masters unreachable: page operations, back off, and retry after
  // a probe succeeds. Reads may continue against replicas.
}

Prevention

Monitor master reachability and page before failover scenarios cascade into user-facing writes
Keep cluster.databases entries accurate through host migrations; verify with bin/storage probe after changes
Give write paths a degradation plan (queue writes, serve stale reads) for master-outage windows
Document and rehearse replica-to-master promotion so the impossible-write window stays short

When it happens

Trigger: establishConnection('w') / any save() or write query while every configured master is down: mysqld crashed, host unreachable, network partition, or all masters failing auth. Replicas may still serve reads, which is why only writes die.

Common situations: Master host crash or reboot; network/firewall outage between application and master; wrong master address or credentials in cluster.databases; failover in progress before a new master is promoted.

Related errors

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