Troubleshooting
Solutions to common issues you might encounter when using MobileCLI.
Connection Issues
Cannot connect to host
Symptoms: Client shows "Connection failed" or "Unable to connect"
Check network connectivity
Ensure both devices are on the same network, or use Tailscale for remote access.
Verify host is running
Check that the MobileCLI daemon is running (mobilecli status).
Check firewall settings
Ensure port 9847 (or your configured port) is allowed through your firewall.
Connection drops frequently
Symptoms: Connection works initially but disconnects randomly
Check WiFi stability
Unstable WiFi can cause WebSocket connections to drop. Try moving closer to your router.
Use Tailscale for stability
Tailscale provides a more stable connection than WiFi alone, especially for remote access.
QR code won't scan
Symptoms: Camera doesn't recognize the QR code
Improve lighting
QR scanning works best with good lighting. Avoid glare on the screen.
Adjust distance
Hold your phone 6-12 inches from the screen. Too close or too far can prevent scanning.
Use manual connection
As a fallback, copy the connection details and enter them manually in the client app.
Session Issues
Sessions not appearing
Symptoms: Connected but session list is empty
Start a session on the host
Sessions only appear after you create them on the host machine.
Pull to refresh
On mobile, pull down on the session list to force a refresh.
Messages not syncing
Symptoms: New messages on host don't appear on client
Check connection status
Look for the connection indicator. Green means connected, red means disconnected.
Reconnect
Try disconnecting and reconnecting from the settings menu.
Input not being sent
Symptoms: Typing messages but they don't appear on host
Check if session is waiting for input
Input can only be sent when the CLI is waiting for user input.
Verify session is active
Ended sessions cannot receive input. Start a new session if needed.
CLI Detection Issues
Claude Code not detected
Symptoms: mobilecli setup says Claude Code is not found
Verify installation
Run claude --version in your terminal to verify Claude Code is installed.
Set custom path
Use mobilecli --claude-path /path/to/claude to specify the path manually.
Gemini CLI not detected
Symptoms: Cannot create Gemini sessions
Check PATH
Ensure the Gemini CLI binary is in your system PATH.
Specify full path
Use the full path to the Gemini binary in MobileCLI settings.
Still Need Help?
If you're still experiencing issues: