phacility/phabricator · error · PhabricatorAuthSSHPrivateKeyIncorrectPassphraseException

This private key requires a passphrase, but the wrong passph

Error message

This private key requires a passphrase, but the wrong passphrase was provided. Check that you supplied the correct key and passphrase.

What it means

When ssh-keygen's diagnostics match the 'passphrase' pattern (the key is passphrase-protected) and a passphrase was supplied but decryption still failed, PhabricatorAuthSSHPrivateKeyIncorrectPassphraseException is thrown with this 'wrong passphrase was provided' wording: the key is fine, the passphrase is not.

Source

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

            $pattern));
      }

      if ($ok) {
        $reason = $pattern_reason;
        break;
      }
    }

    if ($reason === $reason_format) {
      throw new PhabricatorAuthSSHPrivateKeyFormatException(
        pht(
          'This private key is not formatted correctly. Check that you '.
          'have provided the complete text of a valid private key.'));
    }

    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 '.

View on GitHub (pinned to 5720a38cfe)

Solutions

Re-enter the correct passphrase for this key
Verify locally: ssh-keygen -y -P 'your passphrase' -f keyfile must succeed
If the passphrase is lost, regenerate the key pair and update the credential - there is no recovery path

Defensive patterns

Strategy: try-catch

Try / catch

try {
  $bare = $private_key->newBarePrivateKey($passphrase);
} catch (PhabricatorAuthSSHPrivateKeyIncorrectPassphraseException $ex) {
  // Wrong passphrase: re-prompt the user (do NOT auto-retry in a loop).
  $passphrase_error = $ex->getMessage();
} catch (PhabricatorAuthSSHPrivateKeyException $ex) {
  throw $ex;
}

Prevention

Validate the passphrase locally (ssh-keygen -y -P '...' -f key) before storing the credential
After changing a key's passphrase, update the stored credential immediately
Show the distinction between wrong-passphrase and bad-format errors to users - it halves debugging

When it happens

Trigger: Calling newBarePrivateKey($passphrase) with a passphrase that does not match this particular encrypted key.

Common situations: Typos, wrong keyboard layout or caps-lock during passphrase entry; the key was re-encrypted with a new passphrase but the stored credential still has the old one; multiple keys with similar passphrases.

Related errors

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