Structured failure knowledge for AI agents — dead ends, workarounds, error chains
Project description
deadend.dev
Structured failure knowledge for AI coding agents.
87 error entries across 14 domains. When AI agents encounter errors, they waste tokens on approaches that are known to fail. deadend.dev tells agents what NOT to try, what actually works, and what error comes next.
Quick Start — Python SDK
from generator.lookup import 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)}%")
Quick Start — CLI
pip install -e .
python -m generator.lookup "CUDA error: out of memory"
python -m generator.lookup --list # show all known errors
Quick Start — MCP Server (Claude Desktop / Cursor)
Add to ~/.claude/claude_desktop_config.json:
{
"mcpServers": {
"deadend": {
"command": "python",
"args": ["-m", "mcp.server"],
"cwd": "/path/to/deadend.dev"
}
}
}
Then Claude will automatically check deadend.dev when encountering errors.
API Endpoints
| Endpoint | Description |
|---|---|
/api/v1/match.json |
Lightweight regex matching (fits in context window) |
/api/v1/index.json |
Full error index with all metadata |
/api/v1/{domain}/{slug}/{env}.json |
Individual error canon |
/api/v1/openapi.json |
OpenAPI 3.1 spec |
/llms.txt |
LLM-optimized error listing (llmstxt.org standard) |
/llms-full.txt |
Complete database dump |
/.well-known/ai-plugin.json |
AI plugin manifest |
Covered Domains (14)
| Domain | Errors | Examples |
|---|---|---|
| python | 20 | ModuleNotFoundError, TypeError, KeyError, MemoryError |
| node | 11 | ERR_MODULE_NOT_FOUND, EACCES, ERR_REQUIRE_ESM, heap OOM |
| docker | 10 | permission denied, no space left, exec format error |
| cuda | 9 | OOM, version mismatch, device-side assert, NCCL timeout |
| git | 6 | failed to push refs, merge conflicts, pathspec errors |
| pip | 6 | build wheel failed, conflicting dependencies |
| typescript | 4 | TS2307, TS2322, TS2345, TS7006 |
| rust | 3 | E0382 borrow, E0308 mismatch, E0277 trait bound |
| go | 3 | undefined reference, imported not used, type mismatch |
| kubernetes | 3 | CrashLoopBackOff, ImagePullBackOff, OOMKilled |
| terraform | 3 | state lock, provider not present, cycle |
| aws | 3 | AccessDenied, ExpiredToken, ResourceNotFound |
| nextjs | 3 | hydration failed, module not found, server component hooks |
| react | 3 | invalid hook call, too many re-renders, update while rendering |
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 Agent Integration
Every page on deadend.dev includes 8 machine-readable formats:
- JSON API — RESTful error data at
/api/v1/{id}.json - match.json — Compact regex-only file (load entire DB into context)
- JSON-LD — Schema.org TechArticle + FAQPage in every
<head> - ai-summary —
<pre id="ai-summary">with KEY=VALUE pairs - llms.txt — llmstxt.org standard
- OpenAPI — Full API specification
- ai-plugin.json — Plugin discovery manifest
- robots.txt — All AI crawlers explicitly welcomed
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
License
MIT (code) · CC BY 4.0 (data)
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file deadends_dev-0.1.0.tar.gz.
File metadata
- Download URL: deadends_dev-0.1.0.tar.gz
- Upload date:
- Size: 189.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3abb2fbbe533107d9be2155096480c4c836c0aa87e5b2ad97316e48941350f42
|
|
| MD5 |
4b9129662f4f4dd78c94afc9cce2d63d
|
|
| BLAKE2b-256 |
d1a5b4b6e0f8c255ed2e06537212ffeb5a0a40320fab1f8cd2c3e64d032233ab
|
File details
Details for the file deadends_dev-0.1.0-py3-none-any.whl.
File metadata
- Download URL: deadends_dev-0.1.0-py3-none-any.whl
- Upload date:
- Size: 304.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cf2e3a1cd12930b9c3678098d0376466892656bc45c0805fd4a4e538123a7b9d
|
|
| MD5 |
96aba79465323367b49de6b9e5590555
|
|
| BLAKE2b-256 |
5e74587fe1ffde8f0ac9107822101eb563dc63d5c1cfb5f1f32550032bd6d393
|
