phacility/phabricator · error · PhutilArgumentUsageException

The public key corresponding to the given private key is unk

Error message

The public key corresponding to the given private key is unknown. Associate the public key with an Almanac device in the web interface before registering hosts with it.

What it means

Usage exception from `bin/almanac register`: the workflow derived the public key from your private key (ssh-keygen -y) and searched PhabricatorAuthSSHKeyQuery with withKeys(...)->withIsActive(true), but found no matching active public key. Registration authenticates the host by key, so the device's public key must already be uploaded and active on an Almanac device before any host can register with the corresponding private key.

Source

Thrown at src/applications/almanac/management/AlmanacManagementRegisterWorkflow.php:148

    // the `--private-key` flag. The file needs to have restrictive permissions
    // before `ssh-keygen` will willingly operate on it.
    $tmp_private = new TempFile();
    Filesystem::changePermissions($tmp_private, 0600);
    execx('chown %s %s', $phd_user, $tmp_private);
    Filesystem::writeFile($tmp_private, $raw_private_key);

    list($raw_public_key) = execx('ssh-keygen -y -f %s', $tmp_private);

    $key_object = PhabricatorAuthSSHPublicKey::newFromRawKey($raw_public_key);

    $public_key = id(new PhabricatorAuthSSHKeyQuery())
      ->setViewer($this->getViewer())
      ->withKeys(array($key_object))
      ->withIsActive(true)
      ->executeOne();

    if (!$public_key) {
      throw new PhutilArgumentUsageException(
        pht(
          'The public key corresponding to the given private key is unknown. '.
          'Associate the public key with an Almanac device in the web '.
          'interface before registering hosts with it.'));
    }

    if ($public_key->getObjectPHID() !== $device->getPHID()) {
      $public_phid = $public_key->getObjectPHID();
      $public_handles = $viewer->loadHandles(array($public_phid));
      $public_handle = $public_handles[$public_phid];

      throw new PhutilArgumentUsageException(
        pht(
          'The public key corresponding to the given private key is already '.
          'associated with an object ("%s") other than the specified '.
          'device ("%s"). You can not use a single private key to identify '.
          'multiple devices or users.',
          $public_handle->getFullName(),

View on GitHub (pinned to 5720a38cfe)

Solutions

In the web UI, open the Almanac device, use Manage -> SSH Keys -> Add Public Key, paste the public key matching your private key, and activate it.
Re-run bin/almanac register afterwards.
If the key exists but is inactive, reactivate it (or upload a new active one) via the device's key management UI.

Example fix

# before
$ ssh-keygen -y -f device.key > device.pub   # not uploaded anywhere
$ bin/almanac register --device web-001 --private-key device.key
Usage Exception: The public key corresponding to the given private key is unknown. ...

# after
# 1) Web UI: Almanac -> web-001 -> Manage -> SSH Keys -> Add Public Key (paste device.pub)
# 2) re-run:
$ sudo bin/almanac register --force --device web-001 --private-key device.key

Defensive patterns

Strategy: validation

Validate before calling

// Verify the private key's public counterpart is an ACTIVE key on the device
list($raw_pub) = execx('ssh-keygen -y -f %s', $private_path);
$key_obj = PhabricatorAuthSSHPublicKey::newFromRawKey($raw_pub);
$match = id(new PhabricatorAuthSSHKeyQuery())
  ->setViewer($viewer)
  ->withKeys(array($key_obj))
  ->withIsActive(true)
  ->executeOne();
if (!$match) {
  throw new RuntimeException('Upload this public key to the device first.');
}

Try / catch

# shell: pre-upload via API/UI before register
# (automation) create device key, then:
bin/almanac register --device "$D" --private-key "$K" || {
  echo "check device key upload (active) in web UI" >&2; exit 1; }

Prevention

Fold 'upload device public key' into the same provisioning script that registers the host.
Upload device keys from the DEVICE's Manage page, never a user's personal SSH settings.
After any key upload, confirm the key shows active before invoking register.

When it happens

Trigger: Uploading the public key to a user account instead of the Almanac device; uploading it while it was deactivated; passing a freshly generated private key whose public counterpart was never uploaded; uploading the key to the device after register already failed.

Common situations: Operators adding the key under Settings -> SSH Public Keys rather than the device's Manage -> SSH Keys page; key order mistakes in provisioning docs; key deactivated by an admin during rotation.

Related errors

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