Troubleshooting

Start here when something isn’t working. Most problems fall into one of four buckets.

If you use the desktop app and Hub won’t start, read its startup screen first. It names the problem — Docker missing, Docker without permission, or a service that failed — and offers a matching button. See Running Companion Hub.

First commands

Whatever the symptom, these tell you where the problem is:


cihub doctor

Checks the machine and the Hub’s identity in one pass: Docker and Compose, the env file and data folder, the tunnel token, the device ID, the operator account, CI Account registration, Docker networks, and whether containers can reach services on the host, such as Ollama. It starts with a box that names the Hub it checks. It exits with status 1 when it finds a failure. See What cihub doctor checks.


cihub status

Shows the Hub containers, the dashboard address, the Cloudflare tunnel state, and the Tailscale address. If Docker isn’t reachable, it prints Docker is not running or not reachable.


cihub app list

Lists every container on the machine, with its status and ports. If Hub is healthy but one app misbehaves, find its container name here, then read its logs with cihub app logs <container-name>.

Triage flow

Run cihub doctor first; each answer sends you to one page in this section.

flowchart TD
    start["Something isn't working"] --> doctor["cihub doctor"]
    doctor -->|"Docker or Docker Compose:<br/>unavailable"| dk["Docker issues"]
    doctor -->|"Docker bridge: blocked<br/>or refused"| ol["Docker issues →<br/>Ollama not reachable"]
    doctor -->|"Registration, Operator,<br/>Device ID, or Tunnel token<br/>flagged"| ci["Common issues"]
    doctor -->|"No failures,<br/>Hub stack still down"| stack["Docker issues →<br/>Hub stack won't start"]
    doctor -->|"No failures, one app<br/>misbehaves"| logs["cihub app logs #lt;container#gt;<br/>and Settings → Logs"]
    logs --> lv["Log viewer"]
    dk & ol & stack & lv & ci -->|"nothing here fixed it"| help["Getting help"]
    click dk "/docs/troubleshooting/docker-issues"
    click ol "/docs/troubleshooting/docker-issues#ollama-not-reachable-from-containers"
    click stack "/docs/troubleshooting/docker-issues#hub-stack-wont-start"
    click lv "/docs/troubleshooting/log-viewer"
    click ci "/docs/troubleshooting/common-issues"
    click help "/docs/troubleshooting/getting-help"

What `cihub doctor` checks

Each line of the report is one check. A red box means at least one line failed. A yellow box means doctor found something worth knowing but nothing that stops the stack from running, such as a Hub that isn’t paired yet.

Line	What it tells you	If it isn’t OK
`Docker`, `Docker Compose`	The Docker CLI can reach the daemon, and the Compose plugin is installed	Docker issues
`Env file`, `Root folder`, `Compose files`	The Hub’s configuration and data folder exist	Run `cihub setup`, then `cihub up`. A missing env file or root folder before your first start is expected
`Tunnel token`	Whether a Cloudflare tunnel token is on disk. `present, no registration marker (tunnel stays off)` means the token is left over from a Hub that was reset	Pair the Hub again — see Device pairing
`Device ID`	Whether the device ID belongs to this machine. `copied from another machine` means the env file came from another machine	See Move your Hub to a new machine
`Operator`	Whether anyone can sign in. `none` on a registered Hub means nobody has claimed it	Run `cihub claim --email <you@example.com>` on the Hub, or sign in once through CI Account
`Registration`, `Portal check-in`	Where the Hub is in pairing with CI Account, and whether CI Account accepted its last check-in. `degraded (portal_rejected)` and `degraded (tunnel_token_missing)` fail the check	Run `cihub register --code <code>` with a fresh pairing code
`CLI vs stack`	Whether the `cihub` you’re running and the Hub stack come from the same release. A proven mismatch fails; a `dev` image with no release tag is only a note. A `cihub` run from a source checkout names no release, so doctor compares commits, and a difference is only a note	Update the older side — see Auto Update with Cron
`Image pin`	Whether the env file names the image that is actually running. If they differ, the Hub reverts to the older image the next time the machine restarts	Follow the fix that doctor prints
`Duplicate DB subnets`, `Hub pool overlaps`, `Orphan compose networks`	Docker network ranges that overlap, or unused app networks	Run `cihub doctor --repair-networks` to remove unused networks
`Docker bridge`	Whether the Hub container can reach services on the host. `blocked` means a host firewall drops the traffic, and doctor prints the `ufw allow` command to fix it. `refused` means the service listens on loopback only. Doctor checks Hub’s own API port, Ollama, vLLM, and Lemonade, plus an MTPLX or speculative-inference server only when its URL is in the env file, and leaves off any service that isn’t listening on the host	Ollama not reachable from containers

Lines that read unknown mean doctor couldn’t ask: for example, Hub not answering when the stack isn’t running.

Where to go next

Symptom	Page
An app won’t start, dashboard unreachable, pairing fails, remote access is offline	Common issues
Docker won’t start, permission denied, disk full, port conflicts, the Hub container exits at startup	Docker issues
You need to read logs	Log viewer
Nothing here fixed it	Getting help

Before running any destructive reset (cihub reset, docker system prune -a), back up first — see Backup and restore.

Common issues Docker issues Log viewer Getting help