Troubleshooting

Troubleshooting

Installation issues

Problem: "Module not found" errors when running the app

• Ensure you've installed dependencies: python -m pip install -r requirements.txt (or python -m pip install -e .)
• Check you're using Python 3.11 or later
• Try creating a virtual environment first

Permission issues

Problem: "Access denied" when trying to access physical drives

• Run ByteRescue as Administrator (double-clicking ByteRescue.bat does this automatically via a UAC prompt)
• On Windows, right-click Command Prompt/PowerShell and choose "Run as administrator" if launching manually
• Some drives may be locked by the OS or another application

GUI won't start

Problem: Double-clicking ByteRescue.bat doesn't open the window

• Run python -m byterescue from a terminal to see error messages directly
• Check that Python is installed and on your PATH
• Verify dependencies are installed
• Check logs/byterescue.log — every run logs its environment (version, Python build, OS, elevation status) at startup, and startup errors are logged there too

Recovery fails or finds nothing

Problem: Recovery scan completes but no files are found

• The drive may have been TRIM'd (SSD) — data may be permanently gone, see Supported File Systems
• Files may have been overwritten by new data
• Try the Hex Viewer to manually inspect the drive
• Check that you're scanning the correct drive/partition
• If using "Recover by File System," confirm the volume is actually FAT12/16/32 — NTFS/exFAT report a clear error instead of silently finding nothing (see Supported File Systems)

Drive not detected

Problem: Physical drive doesn't appear in the drive list

• Run as Administrator
• Ensure the drive is properly connected
• Check Windows Disk Management to see if Windows itself detects the drive
• Some external drives may need to be connected before starting ByteRescue

Crash and error handling

ByteRescue includes crash handling: startup errors are shown in dialogs, file access errors show readable messages, the GUI stays responsive during scans, and recovery errors are caught and logged (see the "Open Log" button in the Recovery Center, or logs/byterescue.log directly).

If you hit a crash:

1. Note the error message shown
2. Check logs/byterescue.log, and the console window if you launched via ByteRescue.bat (ByteRescue.ps1 leaves the elevated console window open and streams events to it live)
3. Set the BYTERESCUE_DEBUG environment variable for verbose DEBUG-level logging, then reproduce
4. Try restarting the application
5. Ensure adequate disk space and permissions

Performance tips

• Scanning large drives (1TB+) can take a while — consider scanning specific folders instead of an entire drive when possible
• USB 2.0 drives are slower than USB 3.0/3.1; SSD recovery is generally faster than HDD
• Signature carving is CPU-intensive
• Close other applications to free up system resources during a large scan

Reporting a bug

If a problem isn't covered here:

1. Check existing issues for something similar
2. Gather: ByteRescue version, Windows version, Python version, steps to reproduce, error messages (screenshots help), and drive type/size
3. Open a bug report
4. Be mindful of sensitive data — don't include personal information in bug reports or log excerpts