Troubleshooting · errors & fixes
Wallet password recovery troubleshooting — the errors that stop people, solved.
Most failed recovery attempts are not hard cases — they are five familiar mistakes: the wrong file, the wrong version, the wrong hash line, the wrong mode, or the wrong expectations. Work through the symptom below and you will usually find the fix in minutes.
By Robbert Bink · ~6 min read · Published 9 August 2026 · Last reviewed: 14 August 2026
Before you blame the tool, check the five usual suspects: (1) the wrong file or one that isn’t encrypted, (2) the wallet version needs a different extractor or mode, (3) the hash line was extracted wrong, (4) the candidate list is empty or malformed, (5) the speed is normal for a memory-hard format. Each entry names the symptom, cause and fix.
btcrecover: the wallet won’t load
| Symptom | Likely cause | Fix |
|---|---|---|
| “Wallet file ... could not be loaded” / “no wallet type matches” | The file is a different wallet than expected, unencrypted, or a version the tool doesn’t read. | Identify the file first (which wallet file is it?), confirm it is actually encrypted, and check the master list for the right tool. Some legacy versions need an extract script instead of a direct read. |
| Wallet.dat loads but finds no encrypted keys | The wallet was never encrypted, or you pointed at a copy that was migrated. | Open a duplicate copy once in an isolated matching client version, but do not infer encryption from whether it opens — an encrypted wallet can load while locked, with the passphrase only needed for private-key operations (wallet.dat FAQ). Check the wallet’s lock/encryption state instead, and keep the original untouched and backed up. |
| Very low speed / no GPU acceleration | The format is memory-hard (scrypt, BIP38, Armory) or GPU support isn’t set up. | Check the benchmarks page for the expected speed class — “slow” is often normal. |
| Run crashed / lost progress | No autosave. | Restart with --autosave progress.sav and resume with --restore progress.sav — alone on the command line (btcrecover walkthrough). |
hashcat: no hashes loaded or token length exception
| Symptom | Likely cause | Fix |
|---|---|---|
| “No hashes loaded” | The hash file is empty, has trailing junk, or the mode doesn’t match the line format. | Check the line starts with the right prefix ($bitcoin$, $electrum$, $ethereum$, $multibit$, $metamask$) and pick the matching mode from the hashcat guide. |
| “Token length exception” | The hash line does not match the token structure expected by the selected mode — usually a wrong hash mode, a malformed hash, or input that does not fit the expected hash layout (truncation, extra fields, prefixes or separators). | Check the hash mode, re-extract the hash with the correct script, and inspect the line for truncation, extra fields, prefixes or separators. This is not a signal to filter passwords out of your wordlist. |
| Wrong mode accepted but nothing cracks | The hash is a different sub-format (e.g. Electrum salt type 4 vs 5). | Use the salt type inside the hash to pick 16600 vs 21700/21800 (Electrum) — details in the Electrum guide. |
| GPU shows 0 H/s or isn’t used | Driver/OpenCL issue, or the format does not support this GPU/parameter set. | Update the GPU driver, verify with hashcat -I, and check whether the exact mode supports your GPU and whether sufficient device memory is available — memory-hard formats can be memory-limited and may perform better on CPU for some parameter sets, but they are not inherently CPU-only. |
Extraction: the hash line looks wrong
- Empty output from bitcoin2john / electrum2john — the file is unencrypted, a different format, or the script needs the right argument order. Re-check the file type first.
- The hash has a filename prefix or trailing text — extractors often prepend the filename (
wallet.dat:$bitcoin$…) or add a label after a space. hashcat needs only the$bitcoin$…part: strip everything before the first colon and anything after the first whitespace. - Electrum 2.8+ wallet “too small to parse” — the wallet is unencrypted or an unsupported version. For a fully encrypted wallet file, identify the BIE1/BIE2 encrypted storage format or let the current extractor detect it — do not expect the raw file to contain readable wallet JSON such as
use_encryption; verification happens after decryption. - MetaMask extraction fails — use the official
metamask2hashcat.pyfrom the hashcat tools folder and point it at the vault data, not the profile folder.
The full extraction flow is in the John the Ripper walkthrough (which covers the *2john scripts) and the hashcat walkthrough.
Wallet-level: opens but looks empty, or “corrupted”
- Wallet opens but the balance is missing — you restored the right wallet with the wrong seed/backup, or the file predates your funds. Not a password problem: check what you actually lost.
- “Wallet file is corrupted” — this is different from a forgotten password. A wrong password gives a wrong-password error; a damaged file gives a parse error. See the wallet.dat guide (corrupted vs forgotten section).
- Old backup won’t open in the modern client — version migration. Use the matching client version (on a copy, never the original) or the identifier to pin the era.
Still stuck?
Run the diagnosis from the top and check the master list for your exact wallet — every row links to the guide that covers its quirks. If the file is genuinely damaged or the version is unsupported by every public tool, that is a different problem from a forgotten password, and this site says so plainly rather than promising otherwise.
Sources & references
Keep going — it’s all free
Not sure what you lost or what’s possible?
Take the quick diagnosis for a first verdict — it stops early when the answer is already clear — then work the search checklist. Everything here is informative, runs offline, and is free to use.