Skip to content
Pywa Cloud is not live yet - there is no running control plane or dashboard to sign up on, and the CLI package is not published. Everything on this site describes a real, working, tested system, not a roadmap - but none of it is something you can actually run against Pywa Cloud today, and commands/flags/behavior can still change before it is.

Troubleshooting

Not logged in. Run pywa cloud login first. — every command except login needs a stored token. Run pywa login.

Could not reach the control plane at <url> — the CLI couldn’t connect at all (a network/ firewall issue) — distinct from an authentication failure, which would connect fine and return a 401/403 instead.

Invalid email or password (signup/login) — exactly that; there’s no separate “account doesn’t exist” vs. “wrong password” message, deliberately, so a failed login attempt can’t be used to enumerate which emails have accounts.

Verify your email address before creating or deploying bots. (403 from bots create or deploy) — signing up sends a verification email, and both actions are blocked until you click the link in it. Check your inbox (and spam folder) for the email from signup; there’s no CLI resend command yet, but the dashboard’s “check your email” screen has a resend action.

pywa deploy says where the deploy stopped (preparing, building, checking, starting) and why, with the failing step’s own output — usually the pip/uv error or your bot’s traceback. The step-by-step deploy log is pywa cloud deployments log <id>. A few failure modes worth knowing about specifically:

  • Python syntax check failed — every .py file in your project is checked before the build even starts, so a syntax error fails fast with a clear file/line rather than a slower, vaguer build failure. If you’re on macOS and see a syntax error in a file you don’t recognize (e.g. ._main.py), that’s not your code — see below.
  • A file like ._main.py shows up in the error — macOS’s tar command writes an invisible “AppleDouble” metadata file (._<name>) alongside any file with extended attributes when you archive a project by hand. These are automatically ignored during the syntax check, so this shouldn’t happen from a current CLI/dashboard version — if you see it, you’re likely using an old version or building the archive with a different tool; update and retry.
  • Project must include one dependency file: uv.lock, pylock.toml, pyproject.toml, or requirements.txt — exactly that; add one of these declaring pywa[server] (not just pywa — the [server] extra is what pulls in the web server your bot actually runs on). If the file is present but doesn’t declare the right extra, the build itself will still succeed, but your bot will fail to start instead (see “keeps restarting” below) — this check only catches the file being missing entirely.
  • Archive too large — the current limit is 50MB. Make sure .venv/__pycache__/.git aren’t being included (excluded automatically by the CLI’s own archive builder, but a hand-built archive via the dashboard’s file-upload flow won’t get that for free).
  • Build timed out — the default build timeout is 10 minutes. A build that legitimately needs longer than that (a very large dependency set) is unusual — check whether a dependency is hanging on a slow/unreachable index first.

After a successful deploy, the bot keeps restarting

Section titled “After a successful deploy, the bot keeps restarting”

Check pywa cloud status for restart_count and whether it’s flagged as a likely restart loop, then pywa cloud logs for what’s actually crashing. The most common first-deploy cause: the bot reads PYWA_TOKEN/PYWA_PHONE_ID and they aren’t set yet. These aren’t something you set by hand — they’re reserved keys the platform injects only once you connect a real WhatsApp number (pywa cloud connect, or the dashboard’s WhatsApp tab); env set will actively refuse them if you try. A crash-looping bot with no WhatsApp number connected yet is expected, not broken.

If the log says When listening for incoming updates, a verify_token must be provided, you’re on a pywa older than 4.5.0, which insists on one. Pywa Cloud answers Meta’s verification handshake itself, so the value is never checked — pass any string (verify_token="unused") or upgrade pywa.

Health check says “unhealthy” — what do the reasons mean?

Section titled “Health check says “unhealthy” — what do the reasons mean?”

Why an HTTP request at all, rather than just checking that your bot’s process is still running? Because “the process exists” and “it’s actually working” aren’t the same thing — a process can be alive but hung or stuck without ever really starting to serve requests, and a simple liveness check won’t catch that (see status’s own caveat in Managing a Running Bot). An unauthenticated GET to your bot gets real proof of life instead — specifically a GET to /__pywacloud_health__, a reserved path nothing in your own app would ever handle (not your webhook, not a @wa.on_flow_request(...) path). Getting a plain 404 back is still real proof your bot started and is genuinely answering requests, not just that some process happens to be alive.

This is deliberately not a request to your actual webhook. An earlier version of this check did exactly that, and it worked — but it meant every single health check logged a genuine WARNING pywa.server: Failed verification challenge: invalid verify token line into your own pywa cloud logs, indistinguishable at a glance from a real failed request. Hitting a path your own app never handles avoids that entirely — a health check now writes nothing to your logs. There’s still no separate /health route, because pywa itself doesn’t have one, and adding one would be a change to pywa made purely for this platform’s convenience.

pywa cloud status (and the dashboard) report one of these for a running bot:

  • ok — healthy: the app answered the reserved path with the 404 expected of a live server.
  • not_running — your bot isn’t running at all; check status first.
  • no_port_mapping — your bot is running but not yet reachable for a health check (typically right after a deploy) — retry in a few seconds.
  • unreachable — your bot is running but didn’t respond to the health check at all (still starting up, or genuinely stuck) — check logs.
  • unexpected_response — your bot responded, but not with the expected 404 — worth checking logs for what’s actually being served.

Rate limits exist on a handful of specific actions - each keyed narrowly, so hitting one doesn’t block anything else you’re doing:

  • Login - 20/minute per IP, and separately 10/minute per email address (so one person hammering their own forgotten password can’t lock a different account out by IP alone).
  • Signup - 10/minute per IP.
  • Resend verification email - 3/minute per account.
  • Triggering a deploy (including rollback) - 10/minute per bot, checked before any build work starts - this one is per-bot, not per-token or per-IP, since the concern is one bot’s own deploy loop eating build resources, not credential abuse.

All temporary and per-minute - wait a minute and retry. None of these apply to your bot’s own incoming WhatsApp traffic, which has a separate, much higher limit (600/minute) sized for real message volume, not account actions.

Include the full output of pywa cloud status and the last 50-100 lines of pywa cloud logs when asking for help — most of what’s needed to diagnose a stuck deploy is in those three, not in describing the symptom alone.