phacility/phabricator · error · Exception

Unable to determine the username to connect with when trying

Error message

Unable to determine the username to connect with when trying to proxy an SSH request within the cluster.

What it means

To proxy an SSH request to another cluster node, this host must connect as its device account; the username comes from the diffusion.ssh-user config via AlmanacKeys::getClusterSSHUser(). If that setting is unset or empty, there is no account to connect as and this exception is thrown.

Source

Thrown at src/applications/diffusion/ssh/DiffusionSSHWorkflow.php:117

    return $refs;
  }

  final protected function getProxyCommand($for_write) {
    $refs = $this->getAlmanacServiceRefs($for_write);

    $ref = head($refs);

    return $this->getProxyCommandForServiceRef($ref);
  }

  final protected function getProxyCommandForServiceRef(
    DiffusionServiceRef $ref) {

    $uri = new PhutilURI($ref->getURI());

    $username = AlmanacKeys::getClusterSSHUser();
    if ($username === null) {
      throw new Exception(
        pht(
          'Unable to determine the username to connect with when trying '.
          'to proxy an SSH request within the cluster.'));
    }

    $port = $uri->getPort();
    $host = $uri->getDomain();
    $key_path = AlmanacKeys::getKeyPath('device.key');
    if (!Filesystem::pathExists($key_path)) {
      throw new Exception(
        pht(
          'Unable to proxy this SSH request within the cluster: this device '.
          'is not registered and has a missing device key (expected to '.
          'find key at "%s").',
          $key_path));
    }

    $options = array();

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Set the cluster SSH user on every node: bin/config set diffusion.ssh-user <user> (commonly 'git')
2. Make sure that username matches sshd AcceptUsers and the device keys installed for that user
3. Retry the push/pull after saving the config

Example fix

# before
diffusion.ssh-user is unset -> intracluster SSH proxying throws
# after
./bin/config set diffusion.ssh-user git

// Guard before attempting to proxy
$username = PhabricatorEnv::getEnvConfig('diffusion.ssh-user');
if ($username === null || !strlen($username)) {
  // block proxying with a clear 'set diffusion.ssh-user' setup message
}

When it happens

Trigger: Any intracluster SSH push or pull (repository on an Almanac cluster service) on an installation where diffusion.ssh-user was never configured.

Common situations: Clusters set up following the device/keys steps but skipping the SSH user config; configuration lost during migrations.

Related errors

• Leader lost: no up-to-date nodes in repository cluster are f
• Failed to generate an intracluster proxy URI even though thi
• Unable to proxy this SSH request within the cluster: this de
• This request is authenticated as a cluster device, but is pe
• Database "%s" is configured as a replica, but specifies a "p

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