GUIDE 07 / TROUBLESHOOTING
Troubleshoot before expanding your search
Separate installation failures, candidate mistakes, wallet mismatches, and performance limits.
The command cannot find a file
Run from the BTCRecover folder or provide full paths. Quote paths containing spaces. Check whether your editor silently added .txt to a filename, and whether your terminal is using the virtual environment you installed into.
python --version
python -m pip --version
python btcrecover.py --helpThese checks identify the active interpreter and confirm that the script is reachable. For missing modules, use the installation guide’s requirements for your wallet type instead of installing unrelated packages.
The expected guess is missing
Use --listpass with a tiny, invented candidate file. Check required tokens, alternative groups, anchors, and typo limits. An anchor is a restriction, so it can exclude the correct password when the remembered position is wrong.
python btcrecover.py --listpass --passwordlist demo-passwords.txt --typos 1 --typos-caseThis example adds a bounded case-change search. Preview it with dummy text before applying a similar rule to private data. Add other typo rules only when they match a plausible mistake.
Counting or searching takes too long
Start by reducing the candidate space. Broad wildcard and typo combinations can become impractical before the wallet-checking phase begins. The project’s resource-usage notes describe duplicate checking, memory use, ETA generation, and worker threads.
Benchmark your actual wallet and settings before considering a GPU. GPU support varies by wallet format; hardware acceleration cannot repair an incorrect search configuration.
No result does not identify the cause
Keep a short run record: code revision, wallet format, command, candidate-file version, completion state, and result. Avoid putting private candidates into shared logs.
For seeds and passphrases, recheck the verification address, derivation path, and address range. For wallet files, confirm you are testing the intended backup. A completed search rules out its tested candidates under its chosen configuration—not every possible recovery.
CONTINUE WITH THE PRIMARY SOURCES
Sources & further reading
Commands and capabilities can change. Check the maintained documentation for your wallet and installed revision.