When something won’t connect.

You scanned or pasted something that isn’t a CodeMote code: a different QR, a truncated copy-paste, or a screenshot that didn’t decode.

Fix. Scan the QR shown by CodeMote on your computer. Typing it by hand? Use Enter code manually and paste the entire pairing string exactly as VS Code or the CLI shows it.

Pairing codes are single-use. This appears if you scan the same code twice, or the code expired.

Fix. Generate a fresh QR on the host and scan again. Re-scanning a machine you’ve already paired is fine; the app reuses your saved session instead of the one-time code.

Your pairing request reached a backend that isn’t the host that created the code, almost always two CodeMote hosts running for the same workspace, splitting the tunnel between them. (Older builds showed this as the cryptic error 0.)

Fix. Make sure only one host is running for that project: close the duplicate VS Code window or stop the extra codemote start, then scan a fresh QR. See Two hosts, one workspace.

The app couldn’t open the socket to the tunnel URL. Usually the host isn’t running anymore, the tunnel is down or expired, the URL changed since you paired (Cloudflare rotates it on every restart, see Cloudflare), or the phone hit a network wall: captive Wi-Fi, VPN, airplane mode.

Fix. Confirm the host is up and showing a URL, check your provider section, and if the URL rotated, re-pair by scanning the new QR.

The tunnel is likely stopped, or set to Private rather than anonymous, so the handshake never reaches the host.

Fix. On the host, confirm the tunnel is running and its port is public. With the default Cloudflare provider this is automatic. With devtunnel the port must allow anonymous access; with the VS Code Ports panel it must be forwarded and set to Public. Then retry.

The host tunnel went away: computer slept, VS Code closed, or codemote startstopped. The app keeps the old URL and can’t reach it.

Fix. Bring the host back up so the tunnel is live again. CodeMote auto-reconnects to your last workspace once the host is reachable. If the URL changed (Cloudflare), re-pair.

A flaky network, or the host sleeping, drops the socket. CodeMote reconnects automatically with backoff when the host and tunnel come back; you’ll see Reconnecting to ….

Fix. Keep the host awake for long sessions. On a laptop, plug in and disable sleep, or switch to a stable provider so a brief drop doesn’t rotate the URL.

Your saved session token is no longer valid on the host, which restarted with new state or had the token revoked.

Fix. Re-pair by scanning a fresh QR.

The app has that machine in its list but no valid saved credential for it, for example after the keychain was cleared.

Fix. Pair the machine again from the host’s QR.

The phone app and the host are on incompatible protocol versions.

Fix. Update both the CodeMote app (App Store) and the host: the VS Code extension, or npm i -g codemote-cli@latest.

This is devtunnel-specific. A dev tunnel ID belongs to a single Microsoft account, so signing devtunnel into a different account changes the URL your phone was paired to.

Fix. Sign devtunnel back into the original account, or re-pair with the new URL. If repeated logins are the problem, switch to a set-once provider: ngrok or Tailscale.

CodeMote auto-downloads a pinned, checksum-verified cloudflared on first run, cached in ~/.codemote/bin/. If that download fails you’ll see a Could not obtain cloudflared error, a download HTTP <status> or redirect error, or a checksum mismatch. The cause is almost always a locked-down or corporate network, an offline machine, or a proxy that blocks github.com/cloudflare/cloudflared/releases.

Fix. Install cloudflared manually so it’s on your PATH; CodeMote uses the system binary instead of downloading. On macOS: brew install cloudflared (other platforms), then codemote start again. Or switch to a stable provider you install yourself: ngrok or Tailscale.

Timed out waiting for the Cloudflare tunnel URL or cloudflared exited before printing a URL means cloudflared started but never produced a URL, usually a transient Cloudflare outage or a blocked outbound connection. trycloudflare is best-effort and not meant for heavy use.

Fix. Retry. If it persists, or you’re hitting rate limits, switch to a stable provider.

The login session expired.

Fix. Run devtunnel user login again, then codemote start --devtunnel.

The CLI didn’t print a URL in time.

Fix. Check that devtunnel works standalone (devtunnel user show), then retry. A tunnel ID is owned by a single account, so switching accounts changes the URL. If the logins wear on you, switch to ngrok or Tailscale.

ngrok API … failed (HTTP 401) means the key was mistyped or revoked; recreate it and re-run codemote config set ngrok.apiKey <key>. Could not download ngrok means your network blocked the download; install ngrok manually (ngrok.com/download) onto your PATH. ngrok exited before printing a URL usually means another ngrok agent is already running (the free plan allows one session); stop it and retry.

Fix. After fixing the underlying key or network issue, re-run codemote start --ngrok. It’s idempotent, so the one-time authtoken and domain setup finishes on the next run.

tailscale not installed means install it and re-run. not logged in means run tailscale up and finish the browser login. Funnel not available or Funnel is not enabled on your tailnet means the HTTPS certs or the funnelnode attribute aren’t enabled yet; complete the admin-console step above, which can take a minute to propagate.

Fix. If the URL still times out, verify tailscale funnel status works standalone, then retry.

The VS Code extension host can’t run agent chats, only terminals, editor, git and files. The “+” button is disabled on that connection.

Fix. Run the agent from the codemote CLI instead, then scan the QR from that session. Everything else keeps working on either host.

npm i -g codemote-cli
codemote start

You’re on a CLI host that can run agents, but CodeMote couldn’t find the claude executable. It checks your PATH, plus the two spots the installers use even when they’re not on PATH: ~/.local/bin/claude and ~/.claude/local/claude.

Fix. Install Claude Code (claude.ai/code), confirm claude --version runs in a terminal, then restart codemote start. If claudeworks in your normal shell but CodeMote can’t see it, you started codemote from an environment with a different PATH (a systemd unit or bare node); start it from your normal login shell instead.

Same root cause: the host can’t run agents (extension host), or a chat is already starting. On a CLI host with Claude installed, “+” opens the persona picker to start a new chat.

Backgrounding the app tears down the live connection. Reopen CodeMote; it reconnects and replays the terminal so you’re caught up. Long-running commands keep running on the host while you’re away.

Expected. Terminals live on the host, so jobs keep going and are still there when you return.

Make sure you’re connected and editing the Sourceview, not a rendered preview. Use the Rendered / Source toggle to switch back to editable source. If you see “This file changed on the desktop since you opened it,” the file was modified on the host, so reopen it to get the latest.

The agent waiting banner only fires when CodeMote is not the app on screen. Go to the Home screen, switch apps, or lock the device. Pulling Notification Center down over CodeMote still counts as foreground, so no banner shows there. Also confirm notifications are enabled for CodeMote in the iOS Settings app.

Git runs on the host, so a failure usually means the host’s git would fail too: nothing to commit, no upstream, or credentials set up on the computer. Read the message and resolve it on the host. No GitHub sign-in happens on the phone, and no credentials are stored there.