Common issues

Each section below is one symptom, its first check, and the fix. Use the table to jump straight to the one you have. If you’re not sure which applies, run cihub doctor first — see Troubleshooting.

Apps won’t start

• Read the reason first. In the dashboard, open Settings → Logs — an install or start failure is logged there, and the error message links to it. See the Log viewer.
• Check Docker is running: docker info, or cihub doctor
• Ensure enough disk space: df -h and docker system df. See Disk space full.
• Read the container’s own output: run cihub app list to find its container name, then cihub app logs <container-name>

Work through the checks in this order — each one rules out the next:

flowchart TD
    a["App won't start"] --> b{"docker info or<br/>cihub doctor OK?"}
    b -->|"No"| c["Start Docker →<br/>Docker issues"]
    b -->|"Yes"| d{"Disk space left?<br/>df -h · docker system df"}
    d -->|"No"| e["Free space →<br/>Docker issues: Disk space full"]
    d -->|"Yes"| f["Read Settings → Logs, then the app's logs:<br/>cihub app logs #lt;container#gt;"]
    click c "/docs/troubleshooting/docker-issues#docker-not-running"
    click e "/docs/troubleshooting/docker-issues#disk-space-full"
    click f "/docs/troubleshooting/log-viewer"

Error messages you may see

An app’s address says it is starting

Through its Public domain address, an app that is still starting shows <App> is starting… instead of Bad Gateway. Its status is Installing, Starting, Restarting, Updating, Resetting, Backing up, or Restoring, or the app last changed state, or the Hub itself started, less than two minutes ago.

The page reloads itself every five seconds and opens the app as soon as it answers. Nothing needs doing. The visitor’s request still gets the real 502 or 504 status, so API clients and health checks see the failure.

If the page reads <App> isn’t responding, the app didn’t answer for more than two minutes. Check on it in Companion Hub, then reload the page. On a paired Hub the page offers an Open <App> in Companion Hub button.

• Read the reason in Settings → Logs, then the app’s own output: cihub app logs <container-name>.
• Only addresses that go through Hub’s router, the Public domain route, show this page. The Local access address goes straight to the app’s port, so your browser shows its own error there.
• An app that existed before you updated to 0.3.0 gets the page after its next start, restart, or update.

Can’t access dashboard

• Verify Hub is running: cihub status, or check Docker Desktop
• Read the dashboard address from the Containers list in cihub status. The ci-hub row shows <host port>->5002/tcp. The default is http://localhost:5002. If port 5002 was busy when the Hub started, the CLI moved the Hub to a free port and printed a Port preparation box.
• Check that the Hub answers: curl -f http://localhost:5002/api/health/live returns {"status":"ok"}. A first start pulls images, so allow a few minutes before you conclude it is stuck.
• On a remote server, use the server IP, or the Tailscale name from Settings → Network (https://<device>.<tailnet>.ts.net/). The Tailscale IP with port 5002 works only when Tailscale runs on the Hub machine itself. If the address times out, a host firewall may be blocking port 5002.

The address to try depends on where Hub is running:

flowchart TD
    a["Dashboard unreachable"] --> b{"cihub status shows<br/>Hub running?"}
    b -->|"No"| c["Bring the stack up →<br/>Docker issues: Hub stack won't start"]
    b -->|"Yes"| d{"Where is Hub?"}
    d -->|"This machine"| e["http://localhost:5002<br/>or the port in the ci-hub row"]
    d -->|"Remote server"| f["Server IP, or the Tailscale name<br/>from Settings → Network"]
    click c "/docs/troubleshooting/docker-issues#hub-stack-wont-start"

App Store is empty

Hub reads the App Store from Companion Portal, and it authenticates with a device key that it receives when you pair the Hub with your CI Account. A Hub that never finished pairing, or that can’t store the key, fails these calls with a 401. Installs don’t complete, and the store can look slow or empty rather than obviously unauthorized.

• Check pairing: run cihub doctor and read the Registration line. If it says unregistered, run cihub register — see CI Account pairing fails.
• Check that Hub has outbound internet access
• Restart Hub: cihub down, then cihub up --detached

CI Account pairing fails

• Generate a fresh pairing code at hub.ci.computer (codes are single-use). Enter it in the dashboard, or run cihub register --code <code>. Over SSH, --code is required, because the command can’t prompt for it.
• Ensure Hub has outbound internet access, and that the Hub is running — pairing talks to the running Hub.
• If cihub doctor shows Device ID as copied from another machine, the env file came from another machine and Hub refuses to pair under that ID. Fix it first — see Move your Hub to a new machine.
• If the registration page says Unable to reach CI Portal (…), the Hub never reached CI Account. The text in brackets lists each CI Account address and why it failed, for example ETIMEDOUT 192.0.2.10:443 or getaddrinfo ENOTFOUND <host>. Fix DNS, the firewall, your proxy, or your VPN, then register again: the pairing code is still unused. CI Portal did not answer in time means the request went out but nothing came back: get a new code first. cihub doctor shows the same reason on its Portal check-in line.
• If the dashboard says This Hub is not fully set up yet, complete device registration; the message names the phase it’s stuck in.
• See Device pairing for reset steps

This Hub has no operator

Symptom: sign-in fails with This Hub is registered but has no operator yet. Claim it with cihub claim --email <you@example.com> on the Hub itself, or sign in once through CI Portal.

Pairing registers the Hub, but it doesn’t create the first operator account. Run the command on the Hub, with the email address you use for your CI Account:

cihub claim --email <you@example.com>

The command is safe to run again: if the Hub already has an operator, it says so and exits with status 0.

Remote access is offline

Symptom: the dashboard shows a banner, Remote access is offline, and says the Hub runs normally on your device but its public URL isn’t available. Companion Hub itself is unaffected; only the Cloudflare tunnel is down.

• Select Reconnect in the banner. Hub tells you what it needs next: restart the Hub to finish restoring access, or re-pair this device. Re-pairing resets the current registration, so you pair the Hub again.
• Check that the tunnel container exists and is running: docker ps --filter name=cloudflared, then docker logs cloudflared. On an installed Hub, cihub status shows the Cloudflare row as active while the tunnel container runs and not configured otherwise.
• Check that Hub has outbound internet access. The tunnel connects outward to Cloudflare.
• If the state stays stuck after you unpair, see Remove tunnel token manually.

AI models not loading

By default, Hub talks to Ollama running on your machine — from inside the Hub container it connects to http://host.docker.internal:11434.

• Install Ollama on the host: ollama.com , then check it with ollama list
• Run cihub doctor and read the Docker bridge line. refused means Ollama listens on loopback only — set OLLAMA_HOST=0.0.0.0:11434 and restart Ollama. blocked means a host firewall drops traffic from the Hub’s container, and doctor prints the ufw allow command to run. See Ollama not reachable from containers.
• Manage models in Settings → AI. Model downloads run in the background, and their progress appears in Settings → Logs. Large models need several gigabytes of free disk space.
• A download Hub refuses says why at once, for example that the model’s weights are larger than your GPU memory. Pick a smaller model.
• If Lemonade reads Lemonade not detected on Linux although it runs, follow the steps on the Lemonade card. See Lemonade on Linux.

Tailscale not connecting

• If the panel says The Hub could not access Tailscale (no host CLI/socket and no hub-tailscale sidecar), Hub has no Tailscale client to use. Install Tailscale on the Hub machine, or set a pre-auth key, as Sidecar not available describes
• If the panel shows Tailscale refused the Hub’s changes, run the command it shows once on the Hub’s computer. See Tailscale refused the Hub’s changes
• Complete authentication in the browser tab that opens
• Wait 5–10 seconds, then refresh Settings → Network
• See Tailscale troubleshooting