# Troubleshooting & FAQ

## Installation

**Q: `pip install anthropic` fails with SSL error**  
A: Update pip: `python -m pip install --upgrade pip`. If on Windows behind a corporate proxy, set `set HTTPS_PROXY=http://proxy:port`.

**Q: `python` not found on Windows**  
A: Install from python.org. Check "Add Python to PATH" during installation.

**Q: `ModuleNotFoundError: No module named 'yaml'`**  
A: `pip install pyyaml`

## Labs

**Q: Lab returns "No input provided"**  
A: Check you're passing `messages` parameter, not `prompt`. The mock LLM expects: `messages=[{"role": "user", "content": "your prompt"}]`

**Q: Agent loops forever**  
A: `MAX_ITERATIONS` is not set or is too high. Set it to 10-15 for labs.

**Q: Tool call returns empty result**  
A: The mock LLM generates tool calls based on keyword detection. If your prompt doesn't contain trigger words (read, search, write), it won't generate tool calls.

**Q: `str_replace_editor` not found**  
A: That's an Anthropic-specific tool type. The mock LLM only supports basic tool_use blocks. Use the standard tool format shown in the labs.

## Skills

**Q: Installed skills don't appear in `/skills` menu**  
A: Restart Claude Code after installation. Skills are loaded at startup.

**Q: Skill says "not user-invocable"**  
A: Check the YAML frontmatter has `user-invocable: true`. Kit master files intentionally omit this (they're documentation, not invocable skills).

**Q: `$ARGUMENTS` not being replaced**  
A: `$ARGUMENTS` is a placeholder. The agent (Claude Code / Pi) replaces it with your input when you invoke the skill via `/command`.

## API Keys

**Q: "This model is not available" from Anthropic**  
A: You might need to request access to Claude Sonnet 4 / Opus 4. Check [docs.anthropic.com](https://docs.anthropic.com) for available models for your tier.

**Q: Mock LLM works but real API returns 401**  
A: Check `ANTHROPIC_API_KEY` is set correctly. Test with: `python -c "import os; print(os.environ.get('ANTHROPIC_API_KEY', 'NOT SET')[:10])"`

**Q: OpenRouter returns 402 Payment Required**  
A: Your free credits may be exhausted. Add payment method or switch to a different provider.

## General

**Q: The course files use `\u2192` characters that show as garbage**  
A: The course uses Unicode arrows (→) in diagrams. If your terminal doesn't support UTF-8, set `$env:PYTHONIOENCODING='utf-8'` on Windows or use a UTF-8 capable terminal (Windows Terminal, iTerm2, Ghostty).

**Q: How do I cite this course?**  
A: Reference "Agentic Engineering Course" with the module and lesson number.

**Q: Can I teach this course?**  
A: Course materials are provided for personal study. Contact for teaching license.
