0.6. Troubleshooting

When a chapter's verification checkpoint fails, start here. Every entry is a question, symptom-first: find the one that matches what you see, run the diagnostic, then apply the fix. If your problem is not listed, start with the doctor for your current tier: mise run doctor, doctor:model, doctor:gateway, doctor:platform, or doctor:gcp. Use mise run config:check for the agent's resolved configuration.

Why does mise run install or a task fail with "tool not found"?

Symptom: a task exits immediately complaining a binary (uv, kubectl, agentgateway, sops) is missing.

The repository pins every tool in mise.toml but does not auto-install on demand, so hooks and CI fail fast instead of silently drifting. Run mise install once to materialize the pinned toolchain, then run the doctor for the failing layer. mise run doctor checks only the base docs/Python entry path; use doctor:model, doctor:gateway, doctor:platform, or doctor:gcp for their additional external prerequisites. Use mise x -- <tool> to run a pinned tool that is not on your PATH.

Why does the agent fail at startup with a configuration error?

Symptom: adk run, the A2A server, or a task raises a ValidationError before doing any work.

The configuration is validated once at startup (parse, don't validate scattered), so a bad combination fails early with a message that names the fix. Run mise run config:check to see the resolved settings with secrets masked and the exact error. Remove the retired AGENT_GATEWAY_ENABLED variable: deployment topology is selected by OPENAI_BASE_URL, not by changing providers. AGENT_MODEL_PROVIDER=openai-compatible requires an OpenAI-compatible base URL and a non-empty client marker. Use http://127.0.0.1:11434/v1 with direct Ollama in Chapters 2-4 or http://127.0.0.1:4000/v1 with agentgateway in Chapter 5.

Why can't the agent reach Ollama or the model gateway?

Symptom: model calls time out or return connection errors on the local path.

Run mise run doctor:model: Ollama must be reachable and ollama list must contain your AGENT_MODEL, normally qwen3:4b. In Chapters 2-4, OPENAI_BASE_URL points directly to http://127.0.0.1:11434/v1. In Chapter 5, run mise run doctor:gateway, start the loopback wrapper with mise run gateway:host, and change the URL to http://127.0.0.1:4000/v1. Inside Kubernetes, pods reach host Ollama through the gateway, not localhost — a pod's loopback is its own container. A persistent failure after bounded retries is a connectivity problem, not a transient blip.

Why does the agent card request or a port bind time out?

Symptom: a service will not start, or a client cannot reach :3000/:3001/:4000/:8000/:8080.

Something already owns the port. The stable network contract is fixed (MCP :3000, A2A :3001, model :4000, gateway metrics/readiness :15020/:15021, raw MCP :8000, raw A2A :8080, MLflow :5000, Prometheus :9090, host Grafana :3002). Inspect the wrapper with mise run gateway:host:status and mise run gateway:host:logs; stop a stale detached instance with mise run gateway:host:stop. On native Linux, that stop also removes the bridge-only loopback relay. Otherwise find the conflicting process with ss -ltnp | rg ':3001'. Do not run host Compose observability while the in-cluster stack is port-forwarded on the same ports.

Why does an MCP call through the gateway return a 4xx?

Symptom: the agent's MCP tools fail only when routed through the gateway (AGENT_MCP_URL set).

Check three things in order: the MCP server's DNS-rebinding allowlist (MCP_ALLOWED_HOSTS) must include the gateway's hostname; the gateway route must match the path you call; and if the gateway enforces authentication (Chapter 5.5), the caller must send a bearer token — set AGENT_MCP_TOKEN to a minted demo token. A 401/403 is auth, a 404 is a route mismatch, a 421 is a rejected host.

Why do Kubernetes pods stay Pending, CrashLoop, or fail their probes?

Symptom: kubectl -n agentops get pods shows pods not Ready.

Read the events first: kubectl -n agentops get events --sort-by=.lastTimestamp. Common causes: an image that cannot be pulled from registry.localhost:5050 (build and push it with the local skaffold profile); a readiness probe reporting the process cannot serve (the agent and MCP /healthz endpoints check the seed dataset and writable state, not just an open port, so a failing readiness means a real dependency gap); or a pod blocked by a default-deny egress NetworkPolicy — confirm with kubectl -n agentops describe networkpolicy.

Why does mise run test fail the coverage gate after my edit?

Symptom: tests pass but the run fails with "coverage below 95%".

The offline suite enforces at least 95% branch coverage. New source lines need tests that exercise them, including error branches. Run cd agents/python && uv run pytest --cov-report=term-missing to see exactly which lines are uncovered, and add a deterministic test for each — never lower the threshold or add # pragma: no cover to force green.

Why must I remove generated secrets even when the scan passes?

Symptom: a gateway or SOPS lab left private keys in an ignored directory, but mise run secure is green.

Secret detection is heuristic, not proof that no private material exists. The filesystem scanner inspects the SOPS key under infra/secrets/, but a detector may not recognize every age-key encoding. The secured-gateway directory and local .env files are explicit scan exclusions because they are expected runtime secrets and would make every post-lab scan fail.

Git ignores those paths, while staged/full-history gitleaks protects the repository boundary. Tear generated material down using each lab's command, and never force-add it. git status --ignored --short can confirm what remains; a green scanner never authorizes keeping a private key indefinitely.

Why does scripts/check-docs.sh reject my new page?

Symptom: the docs check fails on a page you edited.

Every course page is an FAQ: it must start with --- and a description: front-matter line, contain at least one ## heading, and every ## heading must end with ?. The check also rejects machine-specific absolute paths and stale registry hostnames. Read the failing line it prints and fix the specific heading or front matter.