Why Your Manually Entered Key Fails and How to Fix It
Keys don't work when you type them in for a bunch of different reasons, and they're usually trivial once you narrow it down. I've spent years troubleshooting key imports across GPG, SSH, and various license systems, and the pattern is almost always the same. The first thing I check is whether the key actually has any invisible garbage attached to it. Copy-paste from a PDF, an email, or a web page will frequently smuggle in zero-width spaces, non-breaking spaces, or line-break characters that aren't visible but completely break parsing. The fix is to paste the key into a plain text editor first — notepad on Windows, TextEdit in plain-text mode on Mac, or any terminal-based editor — and then re-copy from there. Takes ten seconds and solves half the tickets I see. The second thing is line length and formatting. Some tools expect keys on single continuous lines without any line breaks. Others expect exactly 72 characters per line with carriage returns. Feed the wrong format to the wrong tool and you get a parse error that gives you no clue what's actually wrong. PGP keys, for instance, are traditionally formatted with 72-character line wrapping. Paste a line-wrapped key into a tool that expects a single line and it fails silently or throws a meaningless error. Paste a single-line key into a tool that expects 72-char wrapping and you may get a different failure. Check the documentation for your specific tool to know which format it accepts, or better yet, use the tool's built-in export function to generate a properly formatted key rather than trying to reconstruct it by hand.
The third common failure mode is key type mismatch. You might be trying to import an Ed25519 key into software that only supports RSA, or a v4 OpenPGP key into a system that only understands v3. This comes up more often than you'd think because people grab the wrong key from their keybase or generate a new one without realizing their target system has a minimum version requirement. I once spent forty-five minutes debugging a situation where a perfectly valid PGP key was being rejected, only to discover the receiving system was an older enterprise appliance that hard-coded support for PGP v3 and refused anything with v4 subpackets. The workaround was to generate the key with the appropriate version flags or downgrade the key ring to the supported format.
What to Actually Do When It Fails
Start by checking the error message, even if it's unhelpful. Most tools will at least tell you whether the failure is a format issue, a checksum mismatch, or an algorithm rejection. If the error says something like "invalid base64" or "malformed packet," you have a format problem. If it says "unsupported key type" or "algorithm not allowed," you have a compatibility problem. If it says nothing at all and just exits with a generic code, you're dealing with a silent parse failure, which usually means invisible characters or wrong line endings. Run a hex dump on the key if you're on a Unix-like system. The command xxd or od -c will show you exactly what bytes are in the file, including any hidden characters that a text editor won't display. This is how I find the non-breaking spaces and zero-width joiners that cause most of the weird failures. On Windows, you can use a hex editor or just paste into a PowerShell session and inspect the string length versus the visible character count — if they don't match, you have invisible characters. Also verify the key fingerprint. If you're importing a public key, compute the fingerprint and compare it against the expected value from the original source. A mismatch means you're not actually importing the right key, which happens more often than people admit, especially when keys rotate or multiple identities share the same email address.
Get the Full Details
Edge Cases That Bite People
Here's one that cost me a afternoon recently. A client sent me a GPG key via encrypted email, and every tool I tried to import it with refused it. The key was valid, the fingerprint matched, the formatting looked correct. The problem turned out to be that the key had been signed by a revocation certificate that had been generated but never published, and some verification tools treat the presence of an unsigned revocation subpacket as a fatal error rather than a warning. I worked around it by stripping the revocation subpacket with gpg --export-options export-minimal before re-importing, which bypassed the problematic signature check while preserving the actual key material. Another thing worth knowing: some systems validate keys against a trust model before they even attempt to use them. If you're importing a key into a system that requires a minimum trust level and the key has never been signed by anyone in the web of trust, it may appear to "not work" when it's actually sitting in a valid but untrusted state. Check the trust settings in your tool, not just the import success or failure.
The Bottom Line
Manual key entry fails most often because of invisible characters, wrong formatting, or a type mismatch. Fix those three things first before digging into anything exotic. If the key still won't work after that, check the error output carefully, compare the fingerprint, and inspect the raw bytes. The answer is almost always in one of those places.
