diff --git a/docs-site/download/index.html b/docs-site/download/index.html index 3c55681..3824d11 100644 --- a/docs-site/download/index.html +++ b/docs-site/download/index.html @@ -254,6 +254,7 @@ footer a{margin:0 8px}

Home Setup guide + Troubleshooting GitHub F-Droid repo Privacy policy diff --git a/docs-site/guide/index.html b/docs-site/guide/index.html index e0b8930..7f603c5 100644 --- a/docs-site/guide/index.html +++ b/docs-site/guide/index.html @@ -304,6 +304,7 @@ OPENCODE_SERVER_PASSWORD=yourpassword opencode serve --hostname 0.0.0.0 --port 4

Home Download + Troubleshooting GitHub F-Droid repo Privacy policy diff --git a/docs-site/index.html b/docs-site/index.html index 2bd1446..38b88ae 100644 --- a/docs-site/index.html +++ b/docs-site/index.html @@ -361,6 +361,7 @@ OPENCODE_SERVER_PASSWORD=yourpassword opencode serve --hostname 0.0.0.0 --port 4

Download Setup guide + Troubleshooting GitHub F-Droid repo Privacy policy diff --git a/docs-site/sitemap.xml b/docs-site/sitemap.xml index 3407a72..6d8d0d1 100644 --- a/docs-site/sitemap.xml +++ b/docs-site/sitemap.xml @@ -15,6 +15,11 @@ monthly 0.8 + + https://dzianisv.github.io/opencode-mobile/troubleshooting/ + monthly + 0.7 + https://dzianisv.github.io/opencode-mobile/privacy/ yearly diff --git a/docs-site/troubleshooting/index.html b/docs-site/troubleshooting/index.html new file mode 100644 index 0000000..e28dcf5 --- /dev/null +++ b/docs-site/troubleshooting/index.html @@ -0,0 +1,200 @@ + + + + + +OpenCode Mobile won't connect? Fix "Network request failed" & connection errors + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +
+ +
+
+
+

OpenCode Mobile won't connect? Here's how to fix it

+

+ OpenCode Mobile is a client — it connects to an opencode server you run yourself. + Most "can't connect" problems come down to one of six causes. The app has a built-in + diagnostic: when a connection fails, tap Share diagnostic to see the exact + classification, then match it to a fix below. +

+
+ First, the 30-second checklist: +
    +
  1. On your machine: opencode serve --hostname 0.0.0.0 --port 4096 (bind 0.0.0.0, not 127.0.0.1, so other devices can reach it).
    2. +
  2. From the phone's browser, open http://<host>:4096/global/health — you should see {"healthy":true}.
    3. +
  3. In the app, use the full URL including http:// and the port, e.g. http://100.108.64.76:4096.
    4. +
+ New here? Start with the setup guide. +
+
+
+ +
+
+

Match the diagnostic to the fix

+ +
+

“The server URL could not be parsed” (malformed URL)

+

Symptom: the app rejects the address before even trying to connect.

+

Include the scheme and port: http://192.168.1.50:4096, not 192.168.1.50 or opencode://…. Remove stray spaces, quotes, or a trailing slash path. Use http:// for a plain local/Tailscale server and https:// only if you put a real TLS certificate in front of it.

+
+ +
+

“No working internet/network” (no internet)

+

Symptom: even a public connectivity check fails.

+

The phone has no usable network. Toggle Wi-Fi/mobile data, and if you connect over a VPN, confirm Tailscale (or your VPN) is connected on the phone. Re-open the app after the network is back.

+
+ +
+

“TLS/certificate problem” (TLS error)

+

Symptom: the handshake fails on an https:// URL.

+

Either switch to http:// (fine for a private LAN/Tailscale link), or fix the server certificate so it's valid and trusted by Android. Self-signed certs will fail unless the cert is installed on the device.

+
+ +
+

“Server reachable but /global/health failed” (health failed)

+

Symptom: the host answers, but the health endpoint returns an error.

+

Usually the wrong path, authentication, or an old server. Confirm the port is the one opencode serve is listening on, update opencode (npm i -g opencode-ai@latest), and if you set OPENCODE_SERVER_PASSWORD, enter the matching username/password in the app.

+
+ +
+

“Connection timed out” (timeout)

+

Symptom: the connection hangs and is dropped, not refused.

+

Something is silently blocking the packets — a firewall, the wrong port, or a Tailscale ACL that doesn't allow your phone to reach the host. Open the port on the host firewall and check your tailnet ACLs permit the device.

+
+ +
+

“Server is unreachable” (server unreachable)

+

Symptom: internet works, but nothing answers at the host:port.

+
    +
  • Confirm opencode serve is actually running and bound to 0.0.0.0.
    • +
  • Confirm the phone is on the same tailnet/LAN as the host.
    • +
  • If you used a hostname and it doesn't resolve, MagicDNS may be off — use the raw Tailscale IP (e.g. http://100.x.y.z:4096).
    • +
  • Double-check the port matches the server.
    • +
+
+
+
+ +
+
+

Still stuck?

+

+ Tap Share diagnostic in the app and open an issue with the report attached — + it includes the classification, the probe results, and recent logs (no code or message + content). File it on + GitHub Issues. +

+

+ See also: the setup guide · download & install · + overview. +

+
+
+
+ + + + +