Troubleshooting

Work from the connector outward. Reinstalling before you know which layer is failing usually makes the problem harder to diagnose.

Start with the symptom

Symptom	Most likely area
No QR code or pairing screen	Connector startup, saved pairing state, or subscription
Pairing waits for approval	The claim is pending on the machine
QR code rejected or expired	Stale code, wrong environment, or a consumed code
Subscription inactive	Store purchase, restore, or billing state
Tunnel disconnected	Network, Cloudflare, credentials, or supervision
Proxy unavailable	Port conflict or local startup failure
OpenCode unavailable	Project path, executable, configuration, or port
Browser login repeats	Wrong browser credential or a regenerated password
Service unreachable	Disabled service, wrong target, auth, or a port conflict
Mobile terminal fails	WebSocket authentication compatibility
App opens but no project appears	OpenCode project context or server response

1. Check the connector status

Open the tray or menu-bar popover and read the OpenCode, Tunnel, and Proxy rows. The CLI prints equivalent phases to the terminal.

• Connecting means the connector is still working. Wait for the retry window before changing settings.
• Retrying shows a sanitized reason. Fix it and choose Retry.
• Error is terminal. Read the reason and the diagnostics log.
• A running cloudflared process alone is not proof of connectivity.

Open Settings → Diagnostics, choose Refresh logs, and look for the first failure rather than a later retry message.

2. Check subscription and pairing

• Confirm OpenCode Mobile came from the App Store or Google Play.
• Open Settings → Cloud Link and confirm the subscription is active.
• Choose Restore purchases if the app was reinstalled.
• Use a fresh connector QR code. Codes expire after five minutes and work once.
• Approve the device on the computer if the app is waiting.
• If credentials were rejected, use Pair device or Settings → Remove saved connection, then pair again.

A machine listed in the app can still be offline. Check that the connector is running before deleting or re-pairing it.

3. Check the tunnel and network

• Confirm the machine has internet access and can resolve api.opencodecloud.link.
• If you changed the control plane, verify it is the expected environment.
• Check for a VPN, firewall, proxy, or DNS policy that blocks outbound HTTPS.
• Wait for capped retries after a network change; transient failures recover on their own.
• If retries stop, fix the reported cause and choose Retry.

Do not repeatedly reset pairing for a network problem. It does not create, register, or repair a remote tunnel.

4. Check OpenCode

• Confirm the working directory exists and contains the project.
• Confirm the configured OpenCode executable is the intended one.
• If a port is occupied, stop the other process or choose another port while disconnected.
• If OpenCode fails after a configuration edit, use Reload in the raw configuration editor and restore the last working file.
• If you adopted an existing server, confirm it is running and reachable on loopback. Adoption deliberately does not kill or replace that process.

5. Check exposed services

• Confirm the service is Enabled.
• Confirm the target is loopback on an allowed port.
• Choose Probe to test reachability.
• Use a supported public port: 8443, 2053, 2083, 2087, or 2096.
• A private service requires Cloud Link credentials. A public service must be explicitly marked public.
• If assets break, try a root service or enable Keep path prefix.
• The reserved /_cloudlink prefix cannot be used as a service path.

6. Check browser access

• Copy the URL and credentials from the connector rather than retyping them.
• Confirm the tunnel is connected.
• Regenerate the browser password if it was exposed or previously rotated.
• A regenerated password signs out existing browser sessions.
• Service URLs on other ports are not the OpenCode URL and may require their own access decision.

7. Platform-specific checks

macOS

• macOS 15 or newer is required.
• If the credential store is locked, unlock it and retry.
• The app hides when its window closes; use the menu-bar icon.
• After a crash, macOS may relaunch the app. An explicit Quit stays stopped.

Windows

• The installer is unsigned; verify the checksum before bypassing SmartScreen.
• WebView2 is provisioned by the installer.
• Check the notification-area overflow for the tray icon.
• Native credentials may need to be unlocked in Credential Manager.

Linux

• Confirm glibc 2.39 or newer.
• Keep the bundled tools together.
• Pair interactively before enabling the systemd user service.
• Read journalctl --user -u opencode-cloudlink.service -f.
• Enable lingering if the service must survive logout.
• Keep awake needs systemd-inhibit and a logind session.

8. Collect a useful report

Include:

• Cloud Link version and platform;
• whether the app is a store build;
• connector status rows and the first sanitized error;
• whether the failure affects pairing, tunnel, OpenCode, proxy, services, or a browser;
• relevant redacted diagnostics.

Never include QR codes, pairing links, public URLs, browser passwords, provider keys, source code, or customer data.

For account, purchase, or privacy requests that cannot be resolved in the app, use the OpenCode Mobile support page. For release-specific issues, check the latest release notes.