1---2name: troubleshoot3description: Diagnose and fix a failing or misbehaving Atomic Agents app — import errors, schema validation failures, empty or malformed LLM output, provider role/mode errors, history and context problems, MCP transport errors. Use when the user reports an error, traceback, or wrong behavior in atomic-agents code, asks "why is my agent not working / crashing / returning garbage", or pastes a `ValidationError`, `ImportError`, or provider API error from an atomic-agents project.4---56# Troubleshoot an Atomic Agents App78Diagnostic workflow for the "it's broken" moment. Most atomic-agents failures are one of a dozen known causes with mechanical fixes. Match the symptom, apply the fix, verify by re-running.910## Workflow11121. **Capture the failure.** Get the exact traceback or wrong-output sample plus the code that produces it (agent construction, schemas, client wiring). If the user pasted only a fragment of the error, ask for the full traceback before guessing.132. **Match against the symptom table below.** The quoted strings are the framework's real messages — match on them.143. **Apply the fix and re-run** the failing snippet. Do not declare the problem solved without a passing re-run.154. **No match?** Load the reference for the failing area (table at the bottom) and reason from there. For a whole-codebase audit rather than one failure, delegate to the `atomic-reviewer` subagent instead.1617## Symptom table1819### Import and definition errors2021| Symptom | Cause | Fix |22|---|---|---|23| `ImportError`/`ModuleNotFoundError` on `atomic_agents.lib.*`, `atomic_agents.agents.base_agent`, or `BaseAgent` | v1 import paths, removed in v2 | Import from the top level: `from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema, BaseTool`; context pieces from `atomic_agents.context` |24| `ValueError: <Name> must have a non-empty docstring to serve as its description` at import time | `BaseIOSchema` subclass without a docstring | Add a docstring describing the schema — it flows into the LLM prompt, so write it for the model |25| `ValidationError` when constructing `AgentConfig`, complaining about `client` | Raw provider SDK client passed; `AgentConfig.client` requires an Instructor-wrapped client | Wrap it: `instructor.from_openai(...)`, `instructor.from_anthropic(...)`, `instructor.from_genai(...)` |26| `TypeError` about missing type parameters, or output typed as `BasicChatOutputSchema` when a custom schema was expected | `AtomicAgent` instantiated without generics | Write `AtomicAgent[InputSchema, OutputSchema](config=...)` — the type parameters carry runtime information (they drive Instructor's `response_model`) |2728### Provider errors at run time2930| Symptom | Cause | Fix |31|---|---|---|32| Anthropic error mentioning `max_tokens` is required | Anthropic requires it per request | `model_api_parameters={"max_tokens": 4096}` on `AgentConfig` |33| Gemini error about invalid role / role ordering | Gemini names the assistant role `model` | `assistant_role="model"` on `AgentConfig`; use `instructor.from_genai(...)` with `mode=Mode.GENAI_TOOLS` and match `AgentConfig.mode` |34| Empty output, `None` fields, or JSON-parse noise on Groq / Ollama / MiniMax | Provider needs JSON mode; factory and config modes disagree | Create the client with `Mode.JSON` and set `mode=Mode.JSON` on `AgentConfig` — the two must always match |35| Works on OpenAI, breaks on another provider with no code change | Provider quirks live in `AgentConfig`, not the agent | Check the per-provider matrix in [framework/references/providers.md](../framework/references/providers.md) |3637### Wrong or degraded behavior (no exception)3839| Symptom | Cause | Fix |40|---|---|---|41| Pydantic `ValidationError` from inside `run()` after retries | Model can't satisfy the output schema | Improve field `description=`s and the schema docstring first; loosen over-tight constraints; only then consider a stronger model. Inspect attempts via the `parse:error` hook |42| Agent "forgets" earlier turns | Fresh `ChatHistory` created per call, or none passed | Create one `ChatHistory` and reuse it across `run()` calls |43| Context/cost grows without bound in long sessions | Unbounded history | Set `max_context_tokens` on `AgentConfig` — oldest turns are trimmed automatically |44| Every `run()` is slow before the LLM call even starts | Blocking I/O in a context provider's `get_info()` | `get_info()` runs on every `run()`; move fetching out, cache, or make the provider hold precomputed state |45| `history.load(...)` "doesn't work" | Called as a classmethod | `load` is an instance method that mutates in place: `history = ChatHistory(); history.load(saved)`. `dump()` returns a JSON string |4647### MCP interop4849| Symptom | Cause | Fix |50|---|---|---|51| `AttributeError: STREAMABLE_HTTP` | No such member | `MCPTransportType.HTTP_STREAM` (others: `SSE`, `STDIO`) |52| MCP tools fetch but calls fail | Transport/endpoint mismatch | See MCP section of [framework/references/tools.md](../framework/references/tools.md) and the `mcp-agent` example |5354## Escalation map5556| Failing area | Load |57|---|---|58| Schema design, validators | [framework/references/schemas.md](../framework/references/schemas.md) |59| Agent config, run modes, streaming | [framework/references/agents.md](../framework/references/agents.md) |60| Provider wiring, roles, modes | [framework/references/providers.md](../framework/references/providers.md) |61| History, persistence, multi-agent memory | [framework/references/memory.md](../framework/references/memory.md) |62| Hooks, retries, telemetry | [framework/references/hooks.md](../framework/references/hooks.md) |63| Tools, MCP | [framework/references/tools.md](../framework/references/tools.md) |64| Orchestration between agents | [framework/references/orchestration.md](../framework/references/orchestration.md) |6566Related skills: `framework` (general guidance, auto-triggers), `create-atomic-agent` / `create-atomic-schema` / `create-atomic-tool` / `create-atomic-context-provider` (building rather than fixing). For a review of code that isn't currently failing, use the `atomic-reviewer` subagent.
eigenwise