opencode-mobile/docs-site/troubleshooting/index.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>OpenCode Mobile won't connect? Fix "Network request failed" &amp; connection errors</title>
<meta name="description" content="Fix OpenCode Mobile connection errors: can't reach opencode serve, network request failed, timeouts, TLS, and Tailscale/MagicDNS issues — a fix for each." />
<meta name="keywords" content="opencode mobile can't connect, opencode serve connection refused, opencode network request failed, opencode tailscale setup, opencode mobile timeout, connect android to opencode server" />
<meta name="theme-color" content="#3b82f6" />
<link rel="canonical" href="https://dzianisv.github.io/opencode-mobile/troubleshooting/" />
<link rel="icon" type="image/png" href="../fdroid/repo/icons/icon.png" />

<meta property="og:type" content="article" />
<meta property="og:site_name" content="OpenCode Mobile" />
<meta property="og:title" content="OpenCode Mobile — fix connection errors" />
<meta property="og:description" content="Step-by-step fixes for OpenCode Mobile connection problems: can't reach opencode serve, timeouts, TLS errors, and Tailscale/MagicDNS issues." />
<meta property="og:url" content="https://dzianisv.github.io/opencode-mobile/troubleshooting/" />
<meta property="og:image" content="https://dzianisv.github.io/opencode-mobile/og.png" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="OpenCode Mobile — fix connection errors" />
<meta name="twitter:description" content="Step-by-step fixes for OpenCode Mobile connection problems." />
<meta name="twitter:image" content="https://dzianisv.github.io/opencode-mobile/og.png" />

<!-- Structured data: Breadcrumb -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "OpenCode Mobile", "item": "https://dzianisv.github.io/opencode-mobile/" },
    { "@type": "ListItem", "position": 2, "name": "Troubleshooting", "item": "https://dzianisv.github.io/opencode-mobile/troubleshooting/" }
  ]
}
</script>

<!-- Structured data: FAQPage -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Why can't OpenCode Mobile connect to my opencode server?",
      "acceptedAnswer": { "@type": "Answer", "text": "Most failures fall into a few buckets: a malformed URL, the device has no internet, a TLS/certificate mismatch, the server is reachable but /global/health fails (wrong path, auth, or old version), a timeout (firewall/port/Tailscale ACL), or the host is simply unreachable (server not running, not on the same tailnet, or MagicDNS off). Tap 'Share diagnostic' in the app to see which one applies." }
    },
    {
      "@type": "Question",
      "name": "Does OpenCode Mobile work over Tailscale?",
      "acceptedAnswer": { "@type": "Answer", "text": "Yes. Run opencode serve --hostname 0.0.0.0 on your machine, install Tailscale on both the machine and the phone, and use the machine's Tailscale IP (or MagicDNS name) and port in the app, e.g. http://100.x.y.z:4096. If a hostname doesn't resolve, MagicDNS may be off — use the raw Tailscale IP." }
    },
    {
      "@type": "Question",
      "name": "What does 'Network request failed' mean in OpenCode Mobile?",
      "acceptedAnswer": { "@type": "Answer", "text": "It is Android's generic error for a connection that never completed. The app runs diagnostics to classify it: no internet, server unreachable, timeout, or TLS error. Check that opencode serve is running and bound to 0.0.0.0, that the phone can reach the host's IP and port, and that any firewall or Tailscale ACL allows the device." }
    }
  ]
}
</script>

<style>
:root{--bg:#0b0f17;--bg-soft:#121826;--card:#161d2e;--border:#243049;--text:#e6ebf5;--muted:#9aa6be;--accent:#3b82f6;--accent-2:#2563eb;}
*{box-sizing:border-box}
html{scroll-behavior:smooth}
body{margin:0;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen,Ubuntu,Cantarell,"Helvetica Neue",Arial,sans-serif;background:var(--bg);color:var(--text);line-height:1.6;-webkit-font-smoothing:antialiased;}
a{color:var(--accent);text-decoration:none}
a:hover{text-decoration:underline}
.wrap{max-width:880px;margin:0 auto;padding:0 20px}
section{padding:36px 0;border-top:1px solid var(--border)}
section:first-of-type{border-top:none}
h1,h2,h3{line-height:1.25;margin:0 0 .5em}
h1{font-size:2.1rem}
h2{font-size:1.4rem;margin-top:.2em}
h3{font-size:1.1rem;margin-top:1.4em}
code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;background:var(--bg-soft);border:1px solid var(--border);border-radius:6px;padding:2px 6px;font-size:.9em;word-break:break-all;}
pre{background:var(--bg-soft);border:1px solid var(--border);border-radius:10px;padding:14px 16px;overflow-x:auto;}
pre code{background:none;border:none;padding:0;word-break:normal}
.crumbs{font-size:.9rem;color:var(--muted);padding-top:24px}
.crumbs a{color:var(--muted)}
.crumbs a:hover{color:var(--accent)}
.lead{font-size:1.12rem;color:var(--muted)}
.err{background:var(--card);border:1px solid var(--border);border-left:3px solid var(--accent);border-radius:10px;padding:16px 18px;margin:16px 0;}
.err h3{margin-top:0}
.err .sym{color:var(--muted);font-size:.95rem}
.muted{color:var(--muted)}
ul li,ol li{margin-bottom:6px}
footer{border-top:1px solid var(--border);padding:32px 0 48px;text-align:center;color:var(--muted);font-size:.9rem;}
footer a{margin:0 8px}
@media(min-width:680px){h1{font-size:2.5rem}}
</style>
</head>
<body>

<div class="wrap">
  <nav class="crumbs" aria-label="Breadcrumb">
    <a href="../">OpenCode Mobile</a> &rsaquo; Troubleshooting
  </nav>
</div>

<main>
<section>
  <div class="wrap">
    <h1>OpenCode Mobile won't connect? Here's how to fix it</h1>
    <p class="lead">
      OpenCode Mobile is a client — it connects to an <code>opencode</code> 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 <strong>Share diagnostic</strong> to see the exact
      classification, then match it to a fix below.
    </p>
    <div class="err">
      <strong>First, the 30-second checklist:</strong>
      <ol>
        <li>On your machine: <code>opencode serve --hostname 0.0.0.0 --port 4096</code> (bind <code>0.0.0.0</code>, not <code>127.0.0.1</code>, so other devices can reach it).</li>
        <li>From the phone's browser, open <code>http://&lt;host&gt;:4096/global/health</code> — you should see <code>{"healthy":true}</code>.</li>
        <li>In the app, use the full URL including <code>http://</code> and the port, e.g. <code>http://100.108.64.76:4096</code>.</li>
      </ol>
      New here? Start with the <a href="../guide/">setup guide</a>.
    </div>
  </div>
</section>

<section>
  <div class="wrap">
    <h2>Match the diagnostic to the fix</h2>

    <div class="err">
      <h3>“The server URL could not be parsed” (malformed URL)</h3>
      <p class="sym">Symptom: the app rejects the address before even trying to connect.</p>
      <p>Include the scheme and port: <code>http://192.168.1.50:4096</code>, not <code>192.168.1.50</code> or <code>opencode://…</code>. Remove stray spaces, quotes, or a trailing slash path. Use <code>http://</code> for a plain local/Tailscale server and <code>https://</code> only if you put a real TLS certificate in front of it.</p>
    </div>

    <div class="err">
      <h3>“No working internet/network” (no internet)</h3>
      <p class="sym">Symptom: even a public connectivity check fails.</p>
      <p>The phone has no usable network. Toggle Wi-Fi/mobile data, and if you connect over a VPN, confirm <strong>Tailscale (or your VPN) is connected</strong> on the phone. Re-open the app after the network is back.</p>
    </div>

    <div class="err">
      <h3>“TLS/certificate problem” (TLS error)</h3>
      <p class="sym">Symptom: the handshake fails on an <code>https://</code> URL.</p>
      <p>Either switch to <code>http://</code> (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.</p>
    </div>

    <div class="err">
      <h3>“Server reachable but /global/health failed” (health failed)</h3>
      <p class="sym">Symptom: the host answers, but the health endpoint returns an error.</p>
      <p>Usually the wrong path, authentication, or an old server. Confirm the port is the one <code>opencode serve</code> is listening on, update opencode (<code>npm i -g opencode-ai@latest</code>), and if you set <code>OPENCODE_SERVER_PASSWORD</code>, enter the matching username/password in the app.</p>
    </div>

    <div class="err">
      <h3>“Connection timed out” (timeout)</h3>
      <p class="sym">Symptom: the connection hangs and is dropped, not refused.</p>
      <p>Something is silently blocking the packets — a firewall, the wrong port, or a <strong>Tailscale ACL</strong> 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.</p>
    </div>

    <div class="err">
      <h3>“Server is unreachable” (server unreachable)</h3>
      <p class="sym">Symptom: internet works, but nothing answers at the host:port.</p>
      <ul>
        <li>Confirm <code>opencode serve</code> is actually running and bound to <code>0.0.0.0</code>.</li>
        <li>Confirm the phone is on the <strong>same tailnet/LAN</strong> as the host.</li>
        <li>If you used a hostname and it doesn't resolve, <strong>MagicDNS may be off</strong> — use the raw Tailscale IP (e.g. <code>http://100.x.y.z:4096</code>).</li>
        <li>Double-check the port matches the server.</li>
      </ul>
    </div>
  </div>
</section>

<section>
  <div class="wrap">
    <h2>Still stuck?</h2>
    <p>
      Tap <strong>Share diagnostic</strong> 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
      <a href="https://github.com/dzianisv/opencode-mobile/issues">GitHub Issues</a>.
    </p>
    <p>
      See also: the <a href="../guide/">setup guide</a> · <a href="../download/">download &amp; install</a> ·
      <a href="../vs-termux/">OpenCode Mobile vs Termux</a> · <a href="../claude-code-android/">using Claude on Android</a> ·
      <a href="../">overview</a>.
    </p>
  </div>
</section>
</main>

<footer>
  <div class="wrap">
    <p>
      <a href="../">Home</a>
      <a href="../download/">Download</a>
      <a href="../features/">Features</a>
      <a href="../guide/">Setup guide</a>
      <a href="../remote-access/">Remote access</a>
      <a href="https://github.com/dzianisv/opencode-mobile">GitHub</a>
      <a href="../privacy/">Privacy policy</a>
    </p>
    <p class="muted">Free and open-source. Built by VIBE TECHNOLOGIES, LLC.</p>
  </div>
</footer>

</body>
</html>