2.9 KiB
2.9 KiB
Troubleshooting
Start with python whatsapp.py --help or the specific command's --help. Commands report compact results; private detailed reports are written locally.
| Symptom | What to check |
|---|---|
| No running Desktop host found | Start the Windows WhatsApp app normally, sign in, and wait until it has loaded. Live commands require x64 Windows and 64-bit Python. |
| Unsupported layout or compatibility warning | A warning means the build is untested; discovery still attempts it. A changed fingerprint/ABI can fail. Keep the detected version and a redacted report for investigation; do not force guessed offsets. |
| Access denied or helper extraction fails | Keep the portable file in a writable folder. Check local security-software diagnostics before changing permissions. Running as administrator is not a routine requirement. |
| Existing output/receipt/configuration | Choose a new export filename. Use webhook install --restore --config listener.json only when reusing that listener configuration. Inspect an uncertain send receipt before retrying. |
| JavaScript tests skipped | Install Node.js and rerun the suite if complete fixture coverage is needed. A passing test run can still contain skips. |
| Webhook token rejected | The direct token must contain 32–128 printable ASCII characters. Supply the named environment variable and ensure the target validates X-Webhook-Token. |
| Direct webhook queue grows | Check HTTPS connectivity, certificates, token authentication and the target's HTTP status. Non-2xx responses leave records queued for retry. The relay disables proxies and redirects. |
| Listener disappears after WhatsApp restart | Process exit destroys injected code. Enable --auto-restore, keep registered file paths stable, and allow up to about a minute after the app has loaded. |
| Restore fails after moving configuration | DPAPI protection is tied to the Windows user/machine. Reconfigure with the endpoint token on the intended user/machine. |
| Stop seems temporary | A restoring configuration can re-enable a listener. Use webhook stop --config listener.json; for full removal follow the task-removal steps in the webhook guide. |
| ZIP contains fewer messages than expected | The export covers locally available rows, not guaranteed full account history or media downloads. Inspect manifest.json and the adjacent report. |
| Export is interrupted | Keep the .partial and report for diagnosis. A new attempt requires a new filename; partial files are not resumed. |
For an automatically restored listener, the configuration records the exact task name. The adjacent listener.status.json reports the last scheduled check; Task Scheduler exposes its last result and next run. A successful scheduler exit alone does not prove message delivery.
When reporting a problem, include the command, Python/app versions and a redacted error/cleanup summary. Do not attach real exports or protected configuration. See security.