# Common Failure Patterns and Fixes

Reference for the Dojo analyzer when deciding how to fix identified weaknesses.

## Terminal / Command Execution

| Error Pattern | Root Cause | Fix |
|---|---|---|
| "command not found" | Tool/binary not in PATH | Add `which` check before execution, suggest install |
| "permission denied" | File/dir not writable | Check permissions first, suggest `chmod` or `sudo` |
| "no such file or directory" | Path doesn't exist | Validate path exists before operations |
| "syntax error" | Bad shell syntax | Use proper quoting and escaping |
| "killed" / exit code 137 | OOM or timeout | Add memory/time limits, suggest smaller scope |

## Web / Network

| Error Pattern | Root Cause | Fix |
|---|---|---|
| "timeout" / "ETIMEDOUT" | Slow server or network | Add retry with backoff, increase timeout |
| "connection refused" | Service not running | Check if service is up before connecting |
| "rate limit" / 429 | API throttling | Add rate limiting, exponential backoff |
| "404 not found" | Wrong URL | Validate URL format, check for typos |
| "SSL certificate" | Cert issues | Flag to user, don't auto-skip verification |

## File Operations

| Error Pattern | Root Cause | Fix |
|---|---|---|
| "ENOENT" | File not found | Check existence first |
| "EACCES" | Permission denied | Check read/write permissions |
| "EISDIR" | Expected file, got dir | Validate file type before operation |
| "disk full" / "ENOSPC" | No space | Check available space, suggest cleanup |

## Vision / AI Model

| Error Pattern | Root Cause | Fix |
|---|---|---|
| "Model ... not supported" | Model removed/renamed by provider | Check `auxiliary.vision.model` in config.yaml — try `openai/gpt-4o`, `google/gemini-2.0-flash-001`, or `anthropic/claude-3-5-sonnet` |
| "invalid model ID" | Typo or deprecated model name | Verify exact model slug on provider's website |
| "unknown variant `image_url`, expected `text`" | Provider doesn't support vision/image input | Switch to a provider that handles vision (OpenRouter, OpenAI, Anthropic) |
| "Failed to take screenshot: Command timed out" | Browser or screenshot tool unresponsive | Increase `browser.command_timeout` in config.yaml, or restart browser |
| "Failed to take screenshot: env: node: No such file" | Node.js missing in sandbox | Install node or check PATH in terminal environment |

## Memory Store

| Error Pattern | Root Cause | Fix |
|---|---|---|
| "Memory at X/Y chars. Adding this entry would exceed the limit" | Memory buffer full | Free space: shorten verbose entries, merge related facts, remove stale info |
| "Replacement would put memory at X/Y chars" | Replacement content longer than available space | Shorten the new content or remove other entries first |
| "No entry matched '...'" | `old_text` in replace/remove doesn't match | Use exact substring — copy verbatim from current memory entry |
| "content is required for 'replace' action" | Missing `content` parameter | Always provide both `old_text` (what to find) and `content` (new text) |
| "old_text is required for 'remove' action" | Missing `old_text` in remove call | Provide the exact substring to identify the entry to remove |

## Skill Management

| Error Pattern | Root Cause | Fix |
|---|---|---|
| "Security scan blocked this skill" | Skill content flagged by security guard | Remove or rephrase flagged patterns (injection, destructive commands, persistence) |
| "Unknown action '...'" | Typo in action parameter | Valid actions: create, edit, patch, delete, write_file, remove_file |
| "Frontmatter must include 'name' field" | Missing YAML frontmatter | Ensure SKILL.md starts with `---\nname: ...\n---` |

## User Correction Signals

| Pattern | Meaning | Action |
|---|---|---|
| "no, I meant..." | Misunderstood intent | Improve skill instructions for disambiguation |
| "ты не дождался одобрения" / "эй без давай" | Agent acted without explicit permission | **CRITICAL**: Always wait for user's explicit "давай" before any action |
| "wrong file/path" | Path resolution error | Add more context-aware path resolution |
| "try again" | Non-specific failure | Need more error details in skill |
| "that broke" | Side effect caused damage | Add safety checks and dry-run options |
| "undo" / "revert" | Want to roll back | Add undo capability to skill |
