phacility/phabricator · error · PhabricatorAuthSSHPrivateKeyUnknownException

This private key could not be opened with the provided passp

Error message

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.

What it means

Fallback branch of PhabricatorAuthSSHPrivateKey: ssh-keygen failed, no pattern matched its diagnostics, and a passphrase was present, so the cause cannot be determined - either the passphrase is wrong or the key text is malformed. The generic PhabricatorAuthSSHPrivateKeyUnknownException tells the user to check both.

Source

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

    if ($reason === $reason_passphrase) {
      if ($passphrase) {
        throw new PhabricatorAuthSSHPrivateKeyIncorrectPassphraseException(
          pht(
            'This private key requires a passphrase, but the wrong '.
            'passphrase was provided. Check that you supplied the correct '.
            '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();

View on GitHub (pinned to 5720a38cfe)

Solutions

Verify the key text is complete: full BEGIN/END lines and intact base64 body
Verify the passphrase by testing locally with ssh-keygen -y -P 'pass' -f keyfile
Re-copy the key from its source and retry; if still failing, regenerate the key pair
Check which ssh-keygen binary runs ('which ssh-keygen') - an unusual build may be producing the opaque diagnostics

Defensive patterns

Strategy: try-catch

Try / catch

try {
  $bare = $private_key->newBarePrivateKey($passphrase);
} catch (PhabricatorAuthSSHPrivateKeyUnknownException $ex) {
  // Cause ambiguous: re-collect BOTH key text and passphrase,
  // and run 'ssh-keygen -y -P ... -f ...' locally to disambiguate.
  $ambiguous_failure = $ex;
} catch (PhabricatorAuthSSHPrivateKeyException $ex) {
  throw $ex;
}

Prevention

Disambiguate locally before retrying: empty-passphrase ssh-keygen success = key unencrypted; passphrase prompt = encrypted; format error = bad text
Pin a known-good openssh-client version on hosts that handle keys - unrecognized diagnostics often come from unusual ssh-keygen builds

When it happens

Trigger: newBarePrivateKey($passphrase) where the installed ssh-keygen version emits an unrecognized error message (version differences are called out in the source comment) while decrypting fails.

Common situations: Exotic or very new/old ssh-keygen builds with diagnostic strings Phabricator does not pattern-match; keys that are simultaneously truncated AND passphrase-protected.

Related errors

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