Import Failures

ZestSSH can import SSH keys (OpenSSH PEM, PuTTY .ppk) and SSH config files. This page covers common import failures and their resolutions.

PuTTY .ppk Import Issues

”Wrong passphrase”

Symptom: Importing an encrypted .ppk file fails with a passphrase error.

Causes:

• The passphrase is incorrect. PPK passphrases are case-sensitive.
• The .ppk file is encrypted. ZestSSH does not support importing encrypted .ppk files directly — you must decrypt the key in PuTTYgen first (Conversions > Export OpenSSH key) and import the unencrypted OpenSSH key.

Solutions:

1. Try re-entering the passphrase carefully.
2. Test the passphrase in PuTTYgen on a Windows machine to verify it is correct.
3. If the passphrase is lost, generate a new key pair and deploy the new public key to your servers.

”This key format is not supported”

Symptom: ZestSSH rejects the .ppk file.

Causes:

• The file may be a PPK version 1 file (very old). ZestSSH supports PPK v2 and v3.
• The file may contain a DSA key. DSA is not supported due to its weak 1024-bit key size.
• The file is not actually a .ppk file (wrong extension or corrupted content).

Solutions:

1. Open the file in a text editor. A valid .ppk file starts with PuTTY-User-Key-File-2: or PuTTY-User-Key-File-3:.
2. If it is a DSA key, generate a new Ed25519 or RSA key instead.
3. If it is PPK v1, open it in a recent version of PuTTYgen, which will convert it to v2/v3 on save.

”No valid SSH keys found in this file”

Symptom: The .ppk file parses but yields no usable key.

Causes:

• The file is a public key only (no private key component).
• The file is corrupted or truncated.

Solutions:

1. Ensure you are importing the private key file, not the public key.
2. Re-export from PuTTYgen or locate the original .ppk file.

OpenSSH Key Import Issues

”Invalid key file format”

Symptom: ZestSSH rejects the file with a format error.

Causes:

• The file does not contain valid PEM headers (-----BEGIN ... PRIVATE KEY-----).
• The file is a public key (.pub) rather than a private key.
• The file contains multiple keys but the first one is malformed.

Solutions:

1. Open the file in a text editor and verify it starts with -----BEGIN and ends with -----END.
2. Ensure you are importing the private key, not the .pub file.
3. If the file came from a non-standard tool, try converting it with ssh-keygen:

   ssh-keygen -p -m PEM -f your_key

“Wrong passphrase. Please try again.”

Symptom: An encrypted key file fails to import.

Causes:

• Incorrect passphrase.
• The key file uses an encryption method that ZestSSH’s underlying library does not support.

Solutions:

1. Try the passphrase again. It is case-sensitive.
2. If you can access a machine with ssh-keygen, test the passphrase:

   ssh-keygen -y -f your_key
   # prompts for passphrase, prints public key on success

3. If the key uses an obscure cipher (e.g. aes-256-cbc with an old KDF), re-encrypt it with a modern method:

   ssh-keygen -p -o -f your_key

   This converts to the modern OpenSSH format with bcrypt KDF.

Ed25519 Keys from Other Tools

Ed25519 keys generated by tools other than OpenSSH (e.g. age, Go’s crypto/ed25519) may use a slightly different encoding. ZestSSH expects the standard OpenSSH wire format. If import fails, re-export the key using ssh-keygen:

ssh-keygen -t ed25519 -f new_key  # generate a new one, or
ssh-keygen -p -o -f existing_key  # re-encode an existing key

SSH Config Import Issues

Partial Import (Some Entries Skipped)

Symptom: Some hosts from your SSH config are imported, but others are missing.

ZestSSH skips entries that fail validation. Check for:

1. Wildcard hosts: Host * entries are intentionally skipped (they are global defaults, not individual connections).
2. Invalid hostnames: Hostnames containing spaces, control characters, or shell metacharacters are rejected.
3. Invalid ports: Ports outside the 1-65535 range are rejected.
4. Invalid usernames: Usernames with control characters or exceeding 128 characters are rejected.
5. Path traversal in IdentityFile: If the IdentityFile path contains .., the entry is skipped as a security precaution.

Solution: Correct the problematic entries in your SSH config file and re-import. ZestSSH logs warnings for each skipped entry.

IdentityFile Not Imported

Symptom: Connections are created but have no SSH key attached.

By design: SSH config import creates connections but does not import the actual key files referenced by IdentityFile. The key files must be imported separately as identities.

Steps:

1. Import the SSH config to create connections.
2. Import each key file individually (Identities > + > Import Key).
3. Assign the imported identities to the corresponding connections.

Unsupported Directives

ZestSSH’s SSH config parser handles a subset of directives:

Directive	Supported
Host	Yes
HostName	Yes
Port	Yes
User	Yes
IdentityFile	Noted but key not auto-imported
ProxyJump	Yes (mapped to Connect Via)
Match	No
Include	No
LocalForward	No
RemoteForward	No
DynamicForward	No
ProxyCommand	No
ControlMaster	No

Unsupported directives are silently ignored during import.

Encoding Issues

Non-UTF-8 Key Files

Symptom: Import fails with garbled characters or unexpected errors.

Cause: The key file may use a non-UTF-8 encoding (e.g. UTF-16, Latin-1). PEM files should always be ASCII or UTF-8.

Solution: Convert the file to UTF-8:

iconv -f UTF-16 -t UTF-8 key_file > key_file_utf8

Line Ending Issues

Symptom: Import fails on a key file created on Windows.

Cause: Windows uses \r\n line endings. While ZestSSH typically handles this, some edge cases may fail.

Solution: Convert to Unix line endings:

dos2unix key_file
# or
sed -i 's/\r$//' key_file