deadends.dev

Install

Config snippet generator goes here (5 client tabs)

README

# deadends.dev

<!-- mcp-name: dev.deadends/deadends-dev -->

[![Errors](https://img.shields.io/badge/errors-2089-blue)](https://deadends.dev)
[![Domains](https://img.shields.io/badge/domains-51-green)](https://deadends.dev)
[![MCP Tools](https://img.shields.io/badge/MCP_tools-8-purple)](https://smithery.ai/server/deadend/deadends-dev)
[![PyPI](https://img.shields.io/pypi/v/deadends-dev)](https://pypi.org/project/deadends-dev/)
[![License](https://img.shields.io/badge/license-MIT%20%2F%20CC%20BY%204.0-lightgrey)](LICENSE)

**Structured failure knowledge for AI coding agents.**

2000+ error entries across 51 domains. When AI coding agents encounter errors, they waste tokens on approaches that are known to fail. deadends.dev tells agents what NOT to try, what actually works, and what error comes next.

> **Website:** [deadends.dev](https://deadends.dev) · **MCP Server:** [Smithery](https://smithery.ai/server/deadend/deadends-dev) · **PyPI:** [deadends-dev](https://pypi.org/project/deadends-dev/) · **API:** [/api/v1/index.json](https://deadends.dev/api/v1/index.json)

## Installation

```bash
pip install deadends-dev
```

**Requirements:** Python 3.10+

## MCP Server

The MCP server exposes 8 tools for AI coding agents:

| Tool | Description |
|------|-------------|
| `lookup_error` | Match an error message against 2000+ known patterns. Returns dead ends, workarounds, and error chains. |
| `get_error_detail` | Get full details for a specific error by ID (e.g., `python/modulenotfounderror/py311-linux`). |
| `list_error_domains` | List all 50 error domains and their counts. |
| `search_errors` | Fuzzy keyword search across all domains (e.g., "memory limit", "permission denied"). |
| `list_errors_by_domain` | List all errors in a specific domain, sorted by fix rate, name, or confidence. |
| `batch_lookup` | Look up multiple error messages at once (max 10). |
| `get_domain_stats` | Get quality metrics for a domain: avg fix rate, resolvability, confidence breakdown. |
| `get_error_chain` | Traverse the error transition graph: what errors follow, precede, or get confused with this one. |

### Local (Claude Desktop / Cursor)

Add to `~/.claude/claude_desktop_config.json`:

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

### Hosted (Smithery — no local setup)

Install via [Smithery](https://smithery.ai/server/deadend/deadends-dev):

```bash
# 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

```python
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

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

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| [`/api/v1/match.json`](https://deadends.dev/api/v1/match.json) | Lightweight regex matching (fits in context window) |
| [`/api/v1/index.json`](https://deadends.dev/api/v1/index.json) | Full error index — includes `page_url` (canonical summary page) |
| [`/api/v1/{domain}/{slug}/{env}.json`](https://deadends.dev/api/v1/python/modulenotfounderror/py311-linux.json) | Individual ErrorCanon ([example](https://deadends.dev/api/v1/python/modulenotfounderror/py311-linux.json)) |
| [`/api/v1/openapi.json`](https://deadends.dev/api/v1/openapi.json) | OpenAPI 3.1 spec with response examples |
| [`/api/v1/stats.json`](https://deadends.dev/api/v1/stats.json) | Dataset quality metrics by domain |
| [`/api/v1/errors.ndjson`](https://deadends.dev/api/v1/errors.ndjson) |