🛠 Troubleshooting Guide

🛠 Troubleshooting Guide

This page provides help for common problems and errors encountered while using the VirusTotal File Scanner. If your issue is not listed, please consult the Discussions or open an Issue.

---

❌ RuntimeError: No runtime library found

Cause: The required pyarmor_runtime.pyd is missing.

Fix:

• Ensure pyarmor_runtime_000000/ folder exists
• File pyarmor_runtime.pyd must be in this folder
• Do not rename or relocate the file

---

❌ Error: Invalid or missing API key

Cause: Your config.py or .env file does not contain a valid VirusTotal API key.

Fix:

• Register at virustotal.com
• Set your key in config.py or .env:

  VT_API_KEY=your-api-key

---

❌ HTTP 403 – API access denied

Cause: Your API key is invalid or has reached the request quota.

Fix:

• Check that your key is correct
• Respect VirusTotal's rate limits:
  • Free API: ~4 requests per minute

---

⚠️ Hash not found

Cause: The scanned file's hash is unknown to VirusTotal.

Fix:

• Optional: Enable full upload mode (not default)
• Or re-check after a few hours

---

❌ UnicodeDecodeError / File encoding issues

Cause: Corrupted or unsupported characters in the file

Fix:

• Avoid scanning binary files with CLI
• Use GUI for binary input (Drag & Drop)

---

❌ Export not working

Cause: Directory ./exports/ does not exist or lacks permission

Fix:

• Manually create the folder:

  mkdir exports

• Ensure your user has write access

---

❌ Logs not written

Cause: Logging is disabled or log path is incorrect

Fix:

• In config.py, set:

  ENABLE_LOGGING = True
  LOG_FILE = "scanner.log"

---

✅ Still stuck?

• Run verify_runtime.py to check runtime presence
• Check scanner.log for error details
• Post your issue on GitHub with steps to reproduce