Troubleshooting ​
Most issues fall into a few buckets. Find yours below. If you're stuck near the end of an hour, don't lose time, switch to the baseline and keep going.
Environment & setup ​
| Symptom | Likely cause | Fix |
|---|---|---|
python: command not found | Python not installed or not on PATH | Re-check Prerequisites. |
ModuleNotFoundError | Virtual environment inactive or deps missing | Activate .venv, then python -m pip install -r requirements.txt. |
pip install fails | Old pip or no network | python -m pip install --upgrade pip, then retry. |
pip install fails building cryptography (Windows on ARM) | No pre-built wheel for ARM64 Windows | Use uv instead: pip install uv, then uv pip install -r requirements.txt. |
| Wrong Python version | Multiple Pythons installed | Use python --version; create the venv with the 3.12 interpreter. |
node: command not found | Node.js not installed or not on PATH | Re-check Prerequisites; install Node.js 20 LTS from https://nodejs.org. |
| Wrong Node.js version | Multiple Node.js versions installed | Use node --version; version must be 20 or higher. |
Authentication & access ​
| Symptom | Likely cause | Fix |
|---|---|---|
| Model auth error | Microsoft Foundry access not set up | Re-check Prerequisites. |
az login issues | Not signed in to Azure | Run az login and select the right subscription. |
| 403 / permission denied | Account lacks access to the resource | Switch to the observe path in Defaults & paths. |
Agent behavior ​
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent answers wrong facts | Missing or too-broad context | Review what the agent retrieves vs. remembers, see Memory. |
| Tool never called | Question doesn't clearly need the tool | Ask explicitly (e.g. "parse the label"). See MCP. |
| Agent forgets earlier turns | Turns don't share a session | Use the same session id; memory middleware is built in Memory. |
| Empty or failed handoff | Callee returns nothing instead of an artifact or error | The contract must always return a structured artifact or an explicit error. See Native tools & A2A handoff. |
MCP connection ​
| Symptom | Likely cause | Fix |
|---|---|---|
Client can't connect / Connection closed | mcp_server.py missing from the repo root, or the backend API isn't running | Copy it if needed (copy baseline\06-1-mcp-server.py mcp_server.py) and confirm the backend responds at http://localhost:8000/health. |
mcp dev fails with Error: typer is required | Inspector extras not installed in the sandbox | Always pass the extras flag: mcp dev --with "mcp[cli]" mcp_server.py. |
| No tools listed | Server failed to register tools | Check the server's startup output for errors. See MCP. |
When all else fails ​
- Switch to the hour's baseline, see How checkpoints work.
- Switch to the observe path for the rest of the hour, see Defaults & paths.
- Flag a facilitator, that's what they're there for. See the Facilitator notes for how they can help.
A failing baseline is an environment problem
If even the provided baseline won't run, it's almost always environment-related, not your code. Don't keep debugging your own work, move to observe and rejoin at the next checkpoint.