phacility/phabricator · error · PhabricatorAuthSSHPrivateKeyUnknownException

This private key could not be opened. This might mean that t

Error message

This private key could not be opened. This might mean that the key requires a passphrase, or might mean that the key is not formatted correctly. Check that you have supplied the complete text of a valid private key and the correct passphrase.

What it means

The no-passphrase twin of the unknown branch: ssh-keygen failed with unrecognized diagnostics and no passphrase was supplied. The thrown PhabricatorAuthSSHPrivateKeyUnknownException explains the key either requires a passphrase or is not formatted correctly.

Source

Thrown at src/applications/auth/sshkey/PhabricatorAuthSSHPrivateKey.php:193

            'key and passphrase.'));
      } else {
        throw new PhabricatorAuthSSHPrivateKeyIncorrectPassphraseException(
          pht(
            'This private key requires a passphrase, but no passphrase was '.
            'provided. Check that you supplied the correct key, or provide '.
            'the passphrase.'));
      }
    }

    if ($passphrase) {
      throw new PhabricatorAuthSSHPrivateKeyUnknownException(
        pht(
          'This private key could not be opened with the provided passphrase. '.
          'This might mean that the passphrase is wrong or that the key is '.
          'not formatted correctly. Check that you have supplied the '.
          'complete text of a valid private key and the correct passphrase.'));
    } else {
      throw new PhabricatorAuthSSHPrivateKeyUnknownException(
        pht(
          'This private key could not be opened. This might mean that the '.
          'key requires a passphrase, or might mean that the key is not '.
          'formatted correctly. Check that you have supplied the complete '.
          'text of a valid private key and the correct passphrase.'));
    }
  }

  private function newTemporaryPrivateKeyFile(PhutilOpaqueEnvelope $key_body) {
    $tmp = new TempFile();

    Filesystem::writeFile($tmp, $key_body->openEnvelope());

    return $tmp;
  }

}

View on GitHub (pinned to 5720a38cfe)

Solutions

Try again with the key's passphrase if it has one
Verify the key text is complete and untruncated (BEGIN/END lines intact)
Test locally: 'ssh-keygen -y -f keyfile' - a passphrase prompt confirms encryption; an error confirms bad format
As a last resort, regenerate the key pair and import the new key

Defensive patterns

Strategy: try-catch

Try / catch

try {
  $bare = $private_key->newBarePrivateKey();
} catch (PhabricatorAuthSSHPrivateKeyUnknownException $ex) {
  // Either the key needs a passphrase or the text is broken:
  // offer the user both prompts (passphrase + re-upload).
  $offer_both = true;
} catch (PhabricatorAuthSSHPrivateKeyException $ex) {
  throw $ex;
}

Prevention

Run 'ssh-keygen -y -f keyfile' locally: a passphrase prompt means supply one; an error means fix the key text
Keep full-file copies of private keys rather than clipboard snippets to avoid truncation

When it happens

Trigger: newBarePrivateKey() without a passphrase where decryption fails for an indeterminate reason on the host's ssh-keygen build.

Common situations: Importing an encrypted key with the passphrase field left blank on a host whose ssh-keygen error text Phabricator cannot classify; malformed keys with no passphrase involved.

Related errors

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