Troubleshooting

If something's off, run ownllm doctor first — nine times out of ten its output is enough to identify the problem. The rest of this page covers the failures doctor flags and how to fix them.

Pairing fails immediately

pair exits with code 2 and pairing key invalid:

• The key has been used. A pairing key is single-use; generate a new one in Admin → Agents → Regenerate pairing key.
• The key has expired (7-day TTL). Same fix.
• You typed it wrong. Pairing keys are 32-char hex; missing or swapped characters are caught by the format check.

Pairing succeeds but the daemon doesn't start

ownllm doctor

Look at the Daemon line. Common causes:

• launchctl bootstrap failed (macOS) — caused by a stale plist from a prior install. Run ownllm service uninstall && ownllm service install.
• systemctl --user says Failed to connect to bus — the user systemd instance isn't running on this distro. Use ownllm service install --system instead.
• Permission denied (Linux) — you tried --system without sudo, or /usr/local/bin/ownllm isn't readable by the service user.

Tunnel never comes up

Symptoms: status shows the daemon online but tunnel red.

ownllm logs --source cloudflared --follow

Common lines:

• failed to connect to edge — the host can't reach Cloudflare edges on TCP 7844. Check egress; some corporate networks block arbitrary outbound TCP. Cloudflared can fall back to HTTPS over 443 — set protocol: http2 in the cloudflared config.
• tunnel credentials invalid — the agent token rotated but the cached cloudflared creds didn't. Run ownllm restart cloudflared.

Models won't load

Run ownllm models list. If a model is error:

• Disk full — ownllm doctor reports it under "Disk free". Models can be 30 GB+; clean up.
• Bad checksum — Ollama caught a partial download. Run ownllm models remove <id> && ownllm models install <id>.
• GPU missing or driver mismatch — Ollama logs say CUDA error: ... or Metal: failed to compile. Update the GPU driver (NVIDIA) or upgrade macOS (Apple).

API requests time out

Symptoms: OPENAI_BASE_URL requests hang for 30 s and return 504.

ownllm logs --source gateway --since 5m

Look for:

• queue full — too many concurrent requests for the model's num_parallel. Raise it with ownllm models config.
• model_does_not_support_tools — the client (Cursor / Claude Code / OpenCode) is sending tool calls but the model doesn't support tools. Switch to a tool-capable model (qwen2.5:32b, llama3.3:70b).
• inference timeout — the model is too big for the host. Pick a lighter recipe.

"Secret store unreachable" on Linux

Headless Linux without D-Bus has no Secret Service to talk to. The CLI prints a one-shot warning and falls back to AES-GCM encrypted files in ~/.config/ownllm/. That's fine for production but it trades the keychain's process-isolation guarantees for filesystem permissions; treat the host accordingly.

Self-update fails

ownllm update

If it can't reach ownllm.app, check egress. If it can but the signature doesn't verify, don't proceed — open an issue, the release pipeline may have a bad artifact.

Where to file an issue

github.com/impulse-studio/ownllm/issues. Include the doctor output (it redacts secrets) and the relevant logs window. Screenshots of stack traces are fine.