FAQ and Troubleshooting

FAQ and Troubleshooting#

This page collects the most common runtime issues and quick fixes.

I cannot send via dashboard#

Symptom:

  • POST /api/send returns 409.

Cause:

  • WhatsApp session is not connected yet.

Fix:

  1. Call POST /api/connect.

  2. Open GET /api/qr and scan QR from Linked Devices.

  3. Confirm GET /api/connection reports connected.

I get invalid WA ID errors#

Symptom:

  • POST /api/send returns 400 with invalid ID message.

Cause:

  • to is not a valid WhatsApp number format.

Fix:

  • Use digits only, optional leading +.

  • Optional @s.whatsapp.net suffix is accepted.

  • Avoid dashes/spaces/letters.

QR is not shown#

Checklist:

  • Ensure runtime state is connecting after /api/connect.

  • Check GET /api/qr output.

  • Use GET /api/debug/summary to inspect events and state transitions.

Disconnect conflict code 440#

Symptom:

  • Session disconnects with conflict behavior (often code 440).

Cause:

  • Another active linked session is competing.

Fix:

  • Keep only one active linked session for testing.

  • Reconnect and scan QR again if required.

Ack timeout on live send test#

Symptom:

  • examples/live_connect.py reports send-ack timeout.

Fix:

  • Verify destination JID is correct.

  • Increase timeout (WATON_ACK_TIMEOUT).

  • Check incoming event logs and network stability.

Editable install fails on Windows (os error 32)#

Symptom:

  • failed to copy ... waton\_crypto.pyd

  • os error 32

Cause:

  • Another running Python process is locking _crypto.pyd.

Fix:

  • Stop running Waton scripts and retry installation.

  • See the README Windows troubleshooting section for PowerShell command.

Docs build fails#

Use strict local build to catch issues:

python -m pip install .[docs]
python -m sphinx -W --keep-going -b html docs/source docs/build/html

If page is missing in nav#

  • Ensure page is listed in docs/source/index.rst toctree.

Useful verification commands#

python -m pytest tests/unit/test_dashboard.py -q
python -m pytest tests/unit/test_messages.py -q
python -m pytest tests/unit/test_client.py -q
python -m pytest tests/unit/test_app.py -q
Contents