Deadends.dev

🚀 deadends.dev

Structured failure knowledge for AI coding agents.

This project provides over 2000 error entries across 51 domains. When AI coding agents encounter errors, they often waste tokens on known - to - fail approaches. deadends.dev informs agents about what not to try, what actually works, and what error might come next.

Website: deadends.dev · MCP Server: Smithery · PyPI: deadends-dev · API: /api/v1/index.json

🚀 Quick Start

Installation

pip install deadends-dev

Requirements: Python 3.10+

MCP Server

The MCP server offers 8 tools for AI coding agents:

Local (Claude Desktop / Cursor)

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "deadend": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/deadends.dev"
    }
  }
}

Hosted (Smithery — no local setup)

Install via Smithery:

# Claude Code
npx -y @smithery/cli@latest install deadend/deadends-dev --client claude

# Cursor
npx -y @smithery/cli@latest install deadend/deadends-dev --client cursor

Or connect directly: https://server.smithery.ai/deadend/deadends-dev

Example Response

When an agent encounters ModuleNotFoundError: No module named 'torch', the lookup_error tool returns:

## ModuleNotFoundError: No module named 'X' (Python 3.11+)
Resolvable: true | Fix rate: 0.88

### Dead Ends (DO NOT TRY):
- pip install X with system Python (fails 70%): venv not activated

### Workarounds (TRY THESE):
- Create venv, activate, then pip install (works 95%)
- Use python -m pip install instead of bare pip (works 90%)

Quick Start — Python SDK

from generator.lookup import lookup, batch_lookup, search

# Single error lookup
result = lookup("ModuleNotFoundError: No module named 'torch'")

# What NOT to try (saves tokens and time)
for d in result["dead_ends"]:
    print(f"AVOID: {d['action']} — fails {int(d['fail_rate']*100)}%")

# What actually works
for w in result["workarounds"]:
    print(f"TRY: {w['action']} — works {int(w['success_rate']*100)}%")

# result["url"] is the canonical summary page URL (e.g. /python/modulenotfounderror/)
print(result["url"])

# Batch lookup (multiple errors at once)
results = batch_lookup([
    "ModuleNotFoundError: No module named 'torch'",
    "CUDA error: out of memory",
    "CrashLoopBackOff",
])

# Keyword search
hits = search("memory limit", domain="docker", limit=5)

Quick Start — CLI

pip install deadends-dev
deadends "CUDA error: out of memory"
deadends --list  # show all known errors

✨ Features

API Endpoints

Covered Domains (51)

ErrorCanon Data Format

Each error is a JSON file with:

{
  "error": { "signature": "...", "regex": "...", "domain": "..." },
  "verdict": { "resolvable": "true|partial|false", "fix_success_rate": 0.88 },
  "dead_ends": [{ "action": "...", "why_fails": "...", "fail_rate": 0.75 }],
  "workarounds": [{ "action": "...", "success_rate": 0.92, "how": "..." }],
  "transition_graph": { "leads_to": [...], "preceded_by": [...] }
}

AI Coding Agent Integration — 18 Discovery Formats

Every page on deadends.dev includes machine - readable data in 18 formats:

🔧 Technical Details

Development

pip install -e ".[dev]"

# Full pipeline (validate → generate → build → test)
python -m generator.pipeline

# Individual steps
python -m generator.bulk_generate     # Generate canons from seeds
python -m generator.build_site        # Build static site
python -m generator.validate          # Validate data + site
python -m pytest tests/ -v            # Run tests

Contributing

Add error definitions to generator/bulk_generate.py or create JSON files directly in data/canons/.

python -m generator.validate --data - only  # Validate before submitting

Changelog

v0.7.0

• Expanded to 2089 error entries across 51 domains (from 1028/20)
• Added 23 new domains: Android, API, Cloud, CMake, Communication, Data, Elasticsearch, Embedded, Flutter, gRPC, Hugging Face, Kafka, LLM, MongoDB, Nginx, OpenCV, Policy, PyTorch, Redis, ROS 2, Security, TensorFlow, Unity
• All domains now have 40+ error entries each
• Fixed 73 regex patterns that didn't match their own signatures

v0.5.0

• page_url field added to index.json, errors.ndjson, and all SDK/MCP responses — always points to the canonical summary page (/domain/slug/), distinct from the env - specific url field
• Lookup SDK url return value now points to the canonical summary page instead of the env - specific page
• MCP tools (match_error, get_error_detail) now return canonical summary URLs
• SEO fixes: Atom feed, IndexNow submissions, JSON - LD TechArticle, and Open Graph tags all corrected to use canonical summary URLs
• Error chain links in HTML templates corrected to point to summary pages rather than noindex env pages

v0.4.0

• Initial public release with 1028 error entries across 20 domains

📄 License

MIT (code) · CC BY 4.0 (data)