Troubleshooting¶
Cluster¶
make cluster-up hangs or fails
Docker probably isn't running, or is out of disk.
Nodes never become Ready
Give it 30 seconds first — NotReady immediately after creation is normal. If it
persists, Docker likely has too little memory. Give Docker at least 6 GB, or use a
single node:
kubectl points at the wrong cluster
The agent inherits your active context — check this before giving it write access.
Agent¶
401 / Unauthorized from the API
Most likely unset in the shell the agent runs in. Exported variables don't follow you into a new terminal tab. Use.env instead.
The API is unreachable on a corporate laptop
A proxy or MDM policy is blocking it. This is common and hard to fix in the room — pair up with a neighbour and drive from their machine.
The agent says it has no tools
Tool definitions aren't reaching the request. They must be sent on every turn of the loop, not just the first.
The agent loops on the same tool call
It isn't seeing the result. Check that tool results are appended to the message history
with the matching tool_use_id.
The agent refuses to make changes
Check RBAC, and check the MCP server's safety flags — read_only blocks all writes:
The agent did something destructive
That's why we run locally. make cluster-down && make cluster-up, and write down what
happened — it's good material for block 6.
Lab-specific¶
Lab 2: pods go into CrashLoopBackOff after hardening
Expected. Most common causes: readOnlyRootFilesystem without an emptyDir for /tmp,
or memory limits set too low. Let the agent find it.
Lab 3: make chaos doesn't seem to have done anything
Give it 30 seconds — some scenarios don't bite until the next reconcile.
Documentation¶
mkdocs serve fails on !!python/name:
Install the pinned dependencies:
Still stuck? Grab a facilitator — that's what we're here for.