ssh-keygen tool.
Understanding the Error Cause
The primary reason for this specific error is a mismatch between the encryption standard used to protect your private key and the capabilities of your current OpenSSH client. Modern systems often generate keys using the Ed25519 or newer RSA algorithms which may be stored in formats that legacy agents reject. Additionally, if the key file was copied from another system or edited manually, it might contain invisible characters, Windows-style line endings (CRLF), or header/footer text that breaks the parser.
Another common culprit is attempting to add a public key instead of a private key. The ssh-add utility expects a private key file, typically named id_rsa, id_ed25519, or similar. If you point it at a .pub file, the format will appear invalid because the structure is fundamentally different. Always verify you are pointing to the correct file extension before troubleshooting further.
Verifying Key File Integrity
Before attempting any fixes, confirm that the file you are trying to add is actually a valid private key. You can inspect the first few lines of the file using the head command. A valid OpenSSH private key should start with -----BEGIN OPENSSH PRIVATE KEY----- or -----BEGIN RSA PRIVATE KEY-----. If you see -----BEGIN PUBLIC KEY-----, you are looking at the wrong file.
head -n 3 ~/.ssh/id_ed25519If the output shows garbage characters or does not match these headers, the file is corrupted. In this case, you likely need to regenerate the key pair. Ensure there are no extra spaces at the end of lines, which can happen if you edited the file in a text editor that auto-formats content. Save the file with Unix-style line endings (LF) rather than Windows-style (CRLF).
Converting or Regenerating the Key
If the key is valid but still rejected, you may need to convert it to a format compatible with your current SSH version. Use ssh-keygen to re-import the key. This process strips out any incompatible metadata and re-encodes it in the standard format.
ssh-keygen -p -f ~/.ssh/id_ed25519This command prompts you to enter the passphrase. If the key has no passphrase, just press Enter. This action effectively "re-writes" the key file in place, ensuring it conforms to the expected structure. If conversion fails, delete the problematic key and generate a new one:
rm ~/.ssh/id_ed25519
ssh-keygen -t ed25519 -C "[email protected]"After generating a new key, add it to the agent using ssh-add ~/.ssh/id_ed25519. This method resolves issues where the key file itself is structurally sound but flagged as invalid due to subtle encoding differences.
Checking Agent and Permissions
Sometimes the issue lies not with the key file but with how the agent interacts with it. Ensure that the ssh-agent is running and that the environment variables are set correctly. You can check if the agent is active by running:
echo $SSH_AUTH_SOCKIf this returns empty, start the agent manually or restart your session. Additionally, verify that the private key file has restrictive permissions. SSH refuses to use keys that are readable by other users. Set the permissions to 600:
chmod 600 ~/.ssh/id_ed25519Incorrect permissions can sometimes manifest as format errors depending on the strictness of the OpenSSH configuration. While less common, SELinux contexts or AppArmor profiles might also block access, though this usually results in permission denied errors rather than format errors. For more details on managing Linux permissions in complex environments, see Understanding Linux Permissions.
Frequently Asked Questions
Why does ssh-add say Invalid Format for a newly generated key?
This often occurs if you are using an outdated version of OpenSSH that does not support the default key type generated by your system, such as Ed25519. Upgrading your OpenSSH client or explicitly generating an RSA key using -t rsa usually resolves this compatibility issue.
Can I convert an old PEM key to the new OpenSSH format?
Yes, you can use ssh-keygen -p -m PEM to convert a key back to the traditional PEM format if your system requires it. However, it is generally recommended to update your server's OpenSSH version to support the newer, more secure OpenSSH format.
Does ssh-add work with public keys?
No, ssh-add is designed exclusively for private keys. Public keys are added to the remote server's ~/.ssh/authorized_keys file, not loaded into the local agent. Attempting to add a public key will always result in a format error.
How do I clear all keys from the ssh-agent?
You can remove all currently loaded keys by running ssh-add -D. This is useful if you suspect a cached key is causing conflicts or if you want to start fresh after changing passphrases.
What if my key file has Windows line endings?
Windows line endings (CRLF) can cause parsing errors. Use a tool like dos2unix to convert the file: dos2unix ~/.ssh/id_ed25519. This ensures the file uses Unix-style LF endings, which OpenSSH expects.