Session 5· Reference

Troubleshooting Guide

What you'll learn
  • ▸Identify schema, tool, and parse errors
  • ▸Fix the most common Session 5 bugs without an instructor
  • ▸Know how to debug a runaway tool loop

Every error below is one students actually hit in Session 5. Click any row to expand the cause and the exact fix. Schema and tool errors are the most common — most have obvious fixes once you know what the API is telling you.

Schema errors (Phase 1)

Tool-calling errors (Phase 2)

Pydantic / parse errors (Phase 3)

Behavioural surprises

"The model ignores my tool and answers in plain text"
Check the tool description. The model needs it to know when the tool is relevant. "Get current weather for a city" beats "get_w".
"Parallel tool calls are not happening"
The model decides whether to parallelise. Make sure the user prompt implies multiple independent operations ("weather in Paris, Tokyo, AND Delhi"). Single-step questions will not trigger parallel calls.
"message.refusal is set but my code still tries to parse"
You must check refusal FIRST. A refusal means the content may be empty or a natural-language apology — not schema JSON.

When nothing above helps

  1. Print the raw response: print(response.model_dump_json(indent=2)) — shows you everything the API returned.
  2. For schema errors, paste your schema into an online JSON Schema validator before using it.
  3. For tool loops, log messages.append() at every step — it is usually a message-ordering bug.
  4. Read the solution with the toggle — diff it against your code line by line.