> ## Documentation Index > Fetch the complete documentation index at: https://docs.b3iq.org/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting Diagnose the most common B3IQ node problems: offline runtimes, unready models, route-readiness gates, stale daemons, and expired claim codes. Most node problems come down to one of a handful of causes: no runtime running, a model that is not installed or not ready, an unsatisfied route-readiness gate, a daemon that is below the minimum version, or an expired claim code. This page walks through each one with the command that confirms it. **Run doctor first** Before anything else, run `b3iq-host doctor`. It checks identity and the local listener, and lists each installed plugin with its state, so you see in one pass whether the box itself is healthy and whether inference is installed and answering. ## Diagnostic commands | Command | What it tells you | | --- | --- | | ` b3iq-host doctor ` | One-shot health check: identity, the local listener, and each installed plugin's state. | | ` sudo b3iq-host plugin list ` | Whether inference is installed, and its state: ready, degraded, down or failed with a reason. | | ` sudo /usr/local/lib/b3iq/plugins/b3iq-inference runtimes ` | With inference installed: which engines are configured and reachable, and the models each serves. | | ` b3iq-host status ` | Enrollment, node identity, and current node state. | | ` b3iq-host version ` | The running host-agent build version. | | ` b3iq-host logs -f ` | Tail live host-agent logs while you reproduce a problem. | | ` curl --fail http://127.0.0.1:8831/health ` | Confirm the local listener is up and answering on loopback. | | ` b3iq-host support-bundle ` | Generate a redacted diagnostics bundle to attach to a support request. | **Support bundles are redacted** `b3iq-host support-bundle` is built to omit secrets: local API keys, node private key material, setup tokens, prompts, and outputs. It is safe to share for diagnostics. Still review the contents before sending if your environment is sensitive. The commands above run on the machine itself. The [`b3iq` CLI](/developers/cli) is a separate account-level tool: sign in once and check any of your machines from anywhere, without a local shell on the node: | Command | What it tells you | | --- | --- | | ` b3iq doctor ` | Account-side check: saved config, auth token, API reachability, and whether cloudflared (needed for b3iq ssh) is installed. | | ` b3iq logs --follow ` | Stream recent gateway request logs for your account. | | ` b3iq ssh ` | Open an SSH session to a machine by name, without a manual ProxyCommand. | ## Common blockers **Runtime offline** No inference engine is running or installed, so the node cannot serve any model. A machine boots without inference, so first check that it is there: `sudo b3iq-host plugin list` shows the inference plugin and its state. If it is missing, install it from the machine's page in your dashboard, or as root with `sudo b3iq-host plugin install inference`. With inference installed, run `sudo /usr/local/lib/b3iq/plugins/b3iq-inference runtimes` to see which engines are configured and reachable. If the list is empty or every engine shows offline, add one from the machine's Models tab in your dashboard, then run the same command again to confirm the engine reports ready. **Model not installed or not ready** A runtime is up, but the model the router would dispatch is not installed, is still downloading, or has not finished its first load. Pick a model profile your machine can actually serve, then watch the install job to completion. The wizard surfaces install progress; you can also tail `b3iq-host logs -f` while the download and first load run. To see install status (installed, downloading, ready) for every profile, list `GET /v1/model-profiles`; `GET /v1/models` lists only the models that can answer right now. A model only counts as ready once it has loaded and can answer. "Downloaded" is not the same as "ready". See [model readiness](/operators/model-readiness) for the full profile fields. **Machine is in Earn mode** A machine switched to Earn mode serves no B3IQ inference by design. It is offered to external GPU marketplaces instead, and SSH and health telemetry are turned off along with it. This is the first thing to check when a machine you expect to be serving looks unreachable or idle. Ask us to move the machine back to Bare metal and it resumes serving your own inference with SSH restored. The move reboots it into the other environment, so the team schedules it with you rather than flipping it underneath you. **Machine online but nothing routes to it** The machine is online but not receiving routed work. Routing requires more than an installed model. Several independent gates must all pass: - **Liveness**: enrolled, a fresh heartbeat, a ready runtime, and the host agent installed as a persistent service. - **Connectivity**: the tunnel and the public inference route are healthy and advertised to the router. - **Claim**: the machine is linked to an owner account. - **Model**: the profile is installed, on a dispatchable route tier, and its runtime queue is healthy. - **Benchmark**: fresh control-plane-observed benchmark evidence exists for the profile. - **Customer policy**: the caller's key accepts the model (key scoping). Start with the machine's Models and Health tabs in [your signed-in dashboard](https://b3iq.org/dashboard/nodes), then read [route readiness](/operators/route-readiness), which lists every blocker and the matching operator action. **Daemon out of date** The Health tab's Lifecycle section shows the running agent version beside the latest one, with an **Update available** badge and an **Update now** button when a verified candidate is staged and waiting. In most cases you do nothing: auto-update is on by default and the control plane applies staged candidates for you. If you turned that toggle off, use **Update now**, then confirm with `b3iq-host version` and `b3iq-host doctor`. See [updates](/operators/updates) for the whole lifecycle. **Claim code expired or node still on step 1** Claim codes are short-lived (roughly 15 minutes), so a code left open in a browser tab will often have expired by the time you use it. If the dashboard is stuck on step 1 or rejects the code, regenerate a fresh one and claim again promptly. An unclaimed node can be re-claimed safely, so regenerating does not strand the machine. If the node already shows as enrolled in `b3iq-host status`, you do not need a new claim code. **Can't reach the dashboard or local APIs** The host agent listens on loopback only by default: ```text http://127.0.0.1:8831 ``` From the machine itself, `curl --fail http://127.0.0.1:8831/health` should succeed. If it does not, the daemon is not running. Check `b3iq-host status` and `b3iq-host logs -f`. If you are trying to reach the listener from another device on your LAN, note that LAN exposure is opt-in and requires explicit configuration plus network controls; loopback will not answer remote requests by design. **Tunnel or public inference disconnected** Routed inference (requests sent through your account's API keys) reaches your node through a Cloudflare tunnel. If the route shows disconnected, you have two options from the host menu: - **Rotate** the tunnel to issue fresh credentials while keeping the same route. Use this for a transient or stuck connection. - **Revoke** the tunnel to tear down public inference entirely. Use this when you are taking the node offline or suspect the credential is compromised. Prefer rotate for recovery; reserve revoke for intentional teardown. After rotating, re-run `b3iq-host doctor` and confirm the route gate clears in [route readiness](/operators/route-readiness). ## When to escalate **B3IQ watches your machines too** An offline machine, a GPU running hot, or a disk nearly full triggers an automatic email to the machine's owner. You don't have to be staring at the dashboard to catch a real problem. **Capture the failing gate** Run `b3iq-host doctor` and note which check fails. Most problems resolve at this step. **Reproduce with logs tailing** Keep `b3iq-host logs -f` open and reproduce the problem so the relevant log lines are captured. **Generate a redacted bundle** Run `b3iq-host support-bundle`. It is built to keep secrets out. **Open a ticket** File the problem, with the bundle attached, from the Support tab in your [dashboard](https://b3iq.org/dashboard/support). ## Related **[Route readiness](/operators/route-readiness)** Every liveness, connectivity, claim, model, benchmark, and customer-policy gate, with the operator action for each. **[Model readiness](/operators/model-readiness)** Model profile fields, route tiers, and what "ready" means. **[Updates](/operators/updates)** How the agent checks, verifies, stages, applies, and rolls back a release. **[Host agent](/operators/host-agent)** The local service, its listener, and the full CLI command map.