What causes "Attempt to connect to %s@%s failed with error #%d: %s." in phacility/phabricator?

Confirm the server is reachable from the Phabricator host exactly as configured: mysql -h -P -u -p

phacility/phabricator · error · AphrontConnectionQueryException

Attempt to connect to %s@%s failed with error #%d: %s.

Error message

Attempt to connect to %s@%s failed with error #%d: %s.

What it means

Thrown by throwConnectionException() when opening a connection fails with an errno that throwCommonException() does not classify into a more specific exception. It wraps the raw error as AphrontConnectionQueryException, e.g. 2002/2003 'Can't connect to MySQL server', name-resolution failures, or 'too many connections' (1040). The $errno of the underlying failure is attached to the exception.

Source

Thrown at src/infrastructure/storage/connection/mysql/AphrontBaseMySQLDatabaseConnection.php:384

        throw new AphrontSchemaQueryException($message);
    }

    // TODO: 1064 is syntax error, and quite terrible in production.

    return null;
  }

  protected function throwConnectionException($errno, $error, $user, $host) {
    $this->throwCommonException($errno, $error);

    $message = pht(
      'Attempt to connect to %s@%s failed with error #%d: %s.',
      $user,
      $host,
      $errno,
      $error);

    throw new AphrontConnectionQueryException($message, $errno);
  }


  protected function throwQueryCodeException($errno, $error) {
    $this->throwCommonException($errno, $error);

    $message = pht(
      '#%d: %s',
      $errno,
      $error);

    throw new AphrontQueryException($message, $errno);
  }

  /**
   * Force the next query to fail with a simulated error. This should be used
   * ONLY for unit tests.
   */

View on GitHub (pinned to 5720a38cfe)

Solutions

Confirm the server is reachable from the Phabricator host exactly as configured: mysql -h<host> -P<port> -u<user> -p
Fix mysql.host/mysql.port (or cluster.databases) if they point at the wrong place
If MySQL refuses with too many connections, raise max_connections and find the connection leak
Treat as transient where appropriate: this is a connect-phase failure, so a retry with backoff after the server returns is safe

Defensive patterns

Strategy: retry

Validate before calling

// Optional liveness probe before dispatching work:
$conn = $dao->establishConnection('r');
queryfx($conn, 'SELECT 1');

Try / catch

$attempts = 3;
do {
  try {
    $conn = $dao->establishConnection('r');
    break;
  } catch (AphrontConnectionQueryException $ex) {
    // Connect-phase failure: transient by nature. Back off, then retry;
    // give up after N attempts and degrade to an availability error.
    if (--$attempts <= 0) {
      throw $ex;
    }
    sleep(pow(2, 3 - $attempts));
  }
} while (true);

Prevention

Monitor mysqld availability and alert before connection storms cascade
Keep mysql.host/mysql.port (or cluster.databases) accurate through infrastructure changes
Size max_connections for daemons + web workers so the server never refuses links
Wrap non-critical read paths to degrade gracefully when the database is briefly unreachable

When it happens

Trigger: Any connection attempt while mysqld is stopped, restarting, or unreachable; wrong mysql.host / mysql.port in configuration; firewall, DNS, or container-network failure between the web host and the database; hitting max_connections so the server refuses new links.

Common situations: MySQL crashed or was restarted during a deploy; config still points at a decommissioned host; Docker/Kubernetes networking rules blocking the port; connection storms from daemons exhausting max_connections; transient cloud/network blips.

Related errors

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