phacility/phabricator · error · PhabricatorAuthSSHPrivateKeySurplusPassphraseException

A passphrase was provided for this private key, but it does

Error message

A passphrase was provided for this private key, but it does not require a passphrase. Check that you supplied the correct key, or omit the passphrase.

What it means

When decrypting a private key fails and a passphrase was supplied, PhabricatorAuthSSHPrivateKey first runs the conclusive test 'ssh-keygen -y -P "" -f <key>' (empty passphrase). If that succeeds, the key has no passphrase at all, so the supplied passphrase is provably surplus and the dedicated PhabricatorAuthSSHPrivateKeySurplusPassphraseException is thrown.

Source

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

    //
    //   - We were given a passphrase, but the key has no passphrase.
    //   - We were given a passphrase, but the passphrase is wrong.
    //   - We were not given a passphrase, but the key has a passphrase.
    //   - The key format is invalid.
    //
    // Our ability to separate these cases varies a lot, particularly because
    // some versions of "ssh-keygen" return very similar diagnostic messages
    // for any error condition. Try our best.

    if ($passphrase) {
      // First, test for "we were given a passphrase, but the key has no
      // passphrase", since this is a conclusive test.
      list($err) = exec_manual(
        'ssh-keygen -y -P %s -f %R',
        '',
        $tmp);
      if (!$err) {
        throw new PhabricatorAuthSSHPrivateKeySurplusPassphraseException(
          pht(
            'A passphrase was provided for this private key, but it does '.
            'not require a passphrase. Check that you supplied the correct '.
            'key, or omit the passphrase.'));
      }
    }

    // We're out of conclusive tests, so try to guess why the error occurred.
    // In some versions of "ssh-keygen", we get a usable diagnostic message. In
    // other versions, not so much.

    $reason_format = 'format';
    $reason_passphrase = 'passphrase';
    $reason_unknown = 'unknown';

    $patterns = array(
      // macOS 10.14.6
      '/incorrect passphrase supplied to decrypt private key/'

View on GitHub (pinned to 5720a38cfe)

Solutions

Leave the passphrase field empty and retry
Confirm you pasted the intended key - the passphrase probably belongs to a different key file
If you meant to use an encrypted key, paste that key's full text instead

Defensive patterns

Strategy: try-catch

Try / catch

try {
  $bare = $private_key->newBarePrivateKey($passphrase);
} catch (PhabricatorAuthSSHPrivateKeySurplusPassphraseException $ex) {
  // Key is unencrypted: retry with no passphrase.
  $bare = $private_key->newBarePrivateKey(new PhutilOpaqueEnvelope(''));
} catch (PhabricatorAuthSSHPrivateKeyException $ex) {
  // All other key/passphrase failures share this abstract base.
  throw $ex;
}

Prevention

Leave the passphrase field empty for unencrypted keys - only fill it when the key asks for one
Confirm the pasted key file is the one the passphrase belongs to
Test locally first: ssh-keygen -y -f keyfile (no -P) succeeding means no passphrase is needed

When it happens

Trigger: Calling newBarePrivateKey($passphrase) with a non-empty passphrase for a key that is not passphrase-protected, e.g. a credential form where the user typed a passphrase while pasting an unencrypted key.

Common situations: Users habitually filling in the passphrase field on every key form; pasting a different (unencrypted) key than the one the passphrase belongs to; automation that always passes a passphrase regardless of key type.

Related errors

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