Troubleshooting

Start at the nearest boundary: local process, SSH, agent, Docker, workload, or client integration.

The TUI does not start

Verify both release binaries are installed together:

command -v yokai
ls -l "$(dirname "$(command -v yokai)")/yokai-tui"
yokai version

If yokai-tui is missing, re-run the installer. Source checkouts may use Bun as a development fallback, but release installs require the sidecar.

The daemon does not start

yokai daemon
curl http://127.0.0.1:7473/health
tail -n 100 ~/.config/yokai/daemon.log

Check whether another process owns port 7473, whether daemon.listen is valid, and whether the config file parses as JSON.

TUI routes return 404 after an upgrade

An older daemon is probably still running. Stop it and relaunch Yokai so the new binary serves current routes. Re-running the installer also performs this restart when ownership is safe.

SSH connection fails

Reproduce outside Yokai with the same inputs:

ssh -p 22 -i ~/.ssh/id_ed25519 ubuntu@gpu-box-01

Then confirm:

• host key and ACL policy allow the connection;
• the key file is readable and has suitable permissions;
• an encrypted key is loaded in ssh-agent;
• the SSH config alias resolves to the expected host, user, and port.

Agent is offline

On the target device:

sudo systemctl status yokai-agent
sudo journalctl -u yokai-agent -n 100 --no-pager
curl -H "Authorization: Bearer <token>" http://127.0.0.1:7474/health

From the operator machine:

yokai devices test <device-id>
yokai devices bootstrap <device-id>

Bootstrap again when the agent binary, token file, or systemd unit is missing or stale.

Docker or GPU preflight fails

Run on the device as the configured SSH user:

docker info
nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
df -h

Add the user to the Docker group or correct the container runtime before retrying bootstrap.

Image pull or model download fails

• Confirm device DNS and outbound HTTPS.
• Authenticate to the image registry when the image is private.
• Add a valid Hugging Face token for gated repositories.
• Confirm the repository and GGUF filenames still exist.
• Retry without --skip-pull if the expected local image is absent.

Service starts but the endpoint fails

Open service logs with Shift+L or:

yokai services logs --follow <device-id> <container-id>

Common causes include insufficient VRAM, incompatible quantization, unsupported GPU architecture, incorrect model flags, a health probe running before model load completes, or a host-port collision. Apply a matching BKC and run the vLLM memory estimate before changing random flags.

Metrics are empty

Check boundaries in order:

1. agent /metrics with bearer authentication;
2. daemon GET /metrics/{deviceID};
3. TUI Dashboard;
4. Prometheus target state for historical monitoring.

The TUI can work even when Prometheus or Grafana is down.

An integration is unavailable

Yokai marks a client available only when it can resolve the expected configuration location. Install or run the client once, ensure its config directory exists, and reopen Settings.

If configuration was incorrect, restore the sibling .yokai.bak file and restart the client.

Collect diagnostics

yokai version
yokai config show
yokai devices list
yokai status
tail -n 200 ~/.config/yokai/daemon.log

Redact hostnames, usernames, filesystem paths, model tokens, and any remaining credentials before sharing output.