Skip to content

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 ​

SymptomLikely causeFix
python: command not foundPython not installed or not on PATHRe-check Prerequisites.
ModuleNotFoundErrorVirtual environment inactive or deps missingActivate .venv, then python -m pip install -r requirements.txt.
pip install failsOld pip or no networkpython -m pip install --upgrade pip, then retry.
pip install fails building cryptography (Windows on ARM)No pre-built wheel for ARM64 WindowsUse uv instead: pip install uv, then uv pip install -r requirements.txt.
Wrong Python versionMultiple Pythons installedUse python --version; create the venv with the 3.12 interpreter.
node: command not foundNode.js not installed or not on PATHRe-check Prerequisites; install Node.js 20 LTS from https://nodejs.org.
Wrong Node.js versionMultiple Node.js versions installedUse node --version; version must be 20 or higher.

Authentication & access ​

SymptomLikely causeFix
Model auth errorMicrosoft Foundry access not set upRe-check Prerequisites.
az login issuesNot signed in to AzureRun az login and select the right subscription.
403 / permission deniedAccount lacks access to the resourceSwitch to the observe path in Defaults & paths.

Agent behavior ​

SymptomLikely causeFix
Agent answers wrong factsMissing or too-broad contextReview what the agent retrieves vs. remembers, see Memory.
Tool never calledQuestion doesn't clearly need the toolAsk explicitly (e.g. "parse the label"). See MCP.
Agent forgets earlier turnsTurns don't share a sessionUse the same session id; memory middleware is built in Memory.
Empty or failed handoffCallee returns nothing instead of an artifact or errorThe contract must always return a structured artifact or an explicit error. See Native tools & A2A handoff.

MCP connection ​

SymptomLikely causeFix
Client can't connect / Connection closedmcp_server.py missing from the repo root, or the backend API isn't runningCopy 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 requiredInspector extras not installed in the sandboxAlways pass the extras flag: mcp dev --with "mcp[cli]" mcp_server.py.
No tools listedServer failed to register toolsCheck the server's startup output for errors. See MCP.

When all else fails ​

  1. Switch to the hour's baseline, see How checkpoints work.
  2. Switch to the observe path for the rest of the hour, see Defaults & paths.
  3. 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.