Troubleshooting

Always start here:

motion doctor

It reports the version, the service type, each component's status, whether the local IDE and the hub are reachable, and whether an update is available.

The box won't come online

• Confirm the agent is connecting: motion status should show agent=1, and motion logs should print connected to wss://motionis.xyz.
• Check the hub is reachable from the box: motion doctor → hub: reachable.
• The hub flips a box offline ~50s after it dies (heartbeat). If it's stuck, re-run the connect one-liner.

"Open IDE" / Terminal / Files do nothing

Usually a local port conflict: the workspace's web server couldn't bind its port, so the tunnel forwards to a dead port. Recent native installs auto-pick free ports, so the fix is to update/reconnect:

motion update      # or re-run the connect one-liner
motion doctor      # 'local IDE: reachable on :NNNNN' confirms it's serving

The file browser shows /workspace

That's the Docker mount point. Two options:

• Pass --root <dir> so the IDE shows the real host path (e.g. --root / shows /). See What the IDE can see.
• Or use the native install, where paths are the host's real paths.

The terminal user looks wrong (Docker)

In Docker the shell is the container's. Re-running connect passes your host user@host into the prompt; for the genuine machine shell, use the native install (--host).

GLIBC_2.36 not found on a native install

The native Linux bundle needs glibc ≥ 2.36 (Ubuntu 24.04+, Debian 12+). On older distros, use Docker mode instead.

Duplicate workspaces piling up

Each install creates a workspace entry. Re-running connect can leave older, offline entries. Delete the stale ones from the dashboard (the trash icon) — only the online one is live.

Metrics / "Tools" tab

• CPU / RAM / Network come from the box's own daemon over the tunnel. CPU and "Host RAM" are whole-machine figures (it's your hardware). Network is a cumulative byte counter.
• The Tools → ports tab is enumerated from Docker on the hub, so it's empty for self-hosted boxes — that's expected, not a failure.

WhatsApp: the bot doesn't reply

• The bot is your own WhatsApp account — message the agent from your note-to-self chat (New chat → tap yourself). It ignores every other conversation, so a message to a different contact gets no reply.
• The first message in a paired-less chat only gets "🔒 link this chat" — send the 6-digit code from Channels → Pair a device first.
• If a message lands mid-reconnect it may lag; send it again.

WhatsApp: can't link (QR won't show / pairing code rejected)

• Prefer the QR — it's more reliable than the phone pairing code.
• Pairing code says "couldn't link device" → the number was wrong: use the phone's exact WhatsApp number in international form, no + and no leading 0 (e.g. 923001234567, not 03001234567).
• Repeated attempts get the number rate-limited by WhatsApp (401 "Connection Failure"). Wait ~30 minutes and try once with the QR.
• Stuck showing the old device after unlinking? Unlink (which logs the device out and wipes the session) then Link again for a fresh QR.

Still stuck?

Grab the logs and open an issue:

motion logs        # live; Ctrl-C to stop