# 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](WEBHOOKS.md). |
| 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](../SECURITY.md).