Deadends Dev

deadends.dev

[](https://deadends.dev/dashboard/) [](https://deadends.dev/dashboard/) [](https://deadends.dev) [](https://deadends.dev) [](https://deadends.dev/country/) [](https://smithery.ai/server/deadend/deadends-dev) [](https://pypi.org/project/deadends-dev/) [](LICENSE)

Stop AI agents from repeating known failures - in code AND in the real world.

AI assistants reliably fumble two kinds of problems: known-failed code fixes, and country-specific real-world rules they've never been exposed to in training. deadends.dev now covers both:

• Code errors (2,089 entries, 51 domains): what NOT to try when an agent

hits ModuleNotFoundError, CUDA OOM, CrashLoopBackOff, etc.

• Country-scoped dead ends (250+ entries across 52 countries): visa rules

(ETA/eVisitor, NZeTA, e-visas, arrival cards), banking requirements, legal red lines (lèse-majesté, §86a, Article 301), cultural taboos (chopsticks in rice, clock gifts in China, red-ink names in Korea), food safety (tap-water safety by country), emergency numbers, driving norms (left-hand traffic), housing contracts - all the friction where a plausible-sounding global answer is wrong locally.

> Why the expansion? Coding dead ends are largely solved by a good LLM. > Country-specific friction - Japanese hanko requirements, Schengen 90/180 > math, Ramadan business hours, Saudi alcohol ban, Indian beef taboos - is > where generic AI advice breaks hardest. The codebase and schema are > identical; the env segment just carries a country code.

> 90% Precision@1 · 0.935 MRR · Data Quality Dashboard

> Website: deadends.dev · MCP Server: Smithery · PyPI: deadends-dev · API: /api/v1/index.json > Repository: https://github.com/dbwls99706/deadends.dev

Why Use This?

| Without deadends.dev | With deadends.dev | |---------------------|-------------------| | Agent tries sudo pip install → breaks system Python → wastes 3 retries | Agent sees "dead end: sudo pip - fails 70%" → skips it immediately | | Agent tells user to tip 15% at a Tokyo restaurant | Agent knows tipping is refused in Japan (culture/tipping-refused/jp) | | Agent drafts a Thai social post referencing King Rama X | Agent stops: Article 112 lèse-majesté risk (legal/lese-majeste-article-112/th) | | Agent fixes error A, gets confused by error B | Agent knows "A leads to B 78% of the time" → handles both | | Agent tells unmarried couple to kiss publicly in Dubai | Agent flags UAE public decency law (legal/unmarried-public-affection/ae) |

What makes this different from asking an LLM?

• Deterministic: Same query → same answer, every time. No hallucination.
• Country-scoped: ID format {domain}/{slug}/{env} - env holds the country

code (kr, jp, us, de...) so the same taboo can be answered differently for different jurisdictions.

• Primary-sourced: Every country canon cites government sites, embassies,

or verifiable reporting. No "based on general knowledge" answers.

• Community-validated: Fix success rates updated from real outcome reports.
• Sub-millisecond: Local regex matching, no API roundtrip.

현실적인 한계 (운영 관점)

• 모든 에러를 다 커버하지는 못합니다. 없는 케이스는 이슈/PR/report_outcome로 빠르게 보완합니다.
• 설명의 깊이보다 실전 해결 우선(dead end/workaround 중심)으로 설계되어 있습니다.
• 신뢰성은 도메인/케이스마다 다를 수 있으므로, 고위험 변경은 공식 문서/벤더 가이드와 교차 검증을 권장합니다.

Quick Start (30 seconds)

pip install deadends-dev
deadends "CUDA error: out of memory"

MCP Server (Claude Desktop / Cursor)

Add to ~/.claude/claude_desktop_config.json:

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

Or install via Smithery (no local setup):

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

MCP Unauthorized 빠른 해결 가이드 (사람용)

deadend: calling "initialize": sending "initialize": Unauthorized 에러가 보이면 아래를 순서대로 그대로 실행/확인하세요.

1) 로컬 서버 모드인지, 원격(Smithery) 모드인지 하나만 사용

# 로컬 서버 확인 (정상 시 툴 목록이 출력됨)
python -m mcp.server --help

2) Claude Desktop 설정 파일 점검 (cwd는 실제 경로여야 함)

cat ~/.claude/claude_desktop_config.json

3) 로컬 서버 직접 실행 테스트

cd /path/to/deadends.dev
python -m mcp.server

4) Smithery 모드라면 재설치(토큰/설정 꼬임 복구)

npx -y @smithery/cli@latest uninstall deadend/deadends-dev --client claude
npx -y @smithery/cli@latest install deadend/deadends-dev --client claude

5) 마지막으로 Claude Desktop 완전 재시작

# macOS 예시
osascript -e 'quit app "Claude"'
open -a Claude

> 팁: Unauthorized는 보통 잘못된 cwd, 중복 서버 설정(로컬+원격 동시), 또는 만료된 인증 상태에서 발생합니다.

Antigravity (Google AI IDE)

Add as a remote MCP server - no authentication required:

{
  "mcpServers": {
    "deadend": {
      "serverUrl": "https://deadends.dev/mcp",
      "type": "http"
    }
  }
}

> Note: Antigravity uses serverUrl (not url). If you get Unauthorized, remove any existing deadend entries from the MCP Store and re-add manually using the config above. See the Antigravity MCP auth guide for general troubleshooting.

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)}%")

# Batch lookup (multiple errors at once)
results = batch_lookup(["error1", "error2", "error3"])

Example Response

## 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%)

MCP Tools (11)

| Tool | Description | |------|-------------| | lookup_error | Match an error message against 2000+ known patterns | | get_error_detail | Full canon by ID | | list_error_domains | All 54 domains with counts | | search_errors | TF-IDF keyword search across all domains | | list_errors_by_domain | All errors in a domain | | list_errors_by_country | All country-scoped dead ends for an ISO alpha-2 code | | get_country_summary | Country-level summary (entries, fix rate, domain mix) | | batch_lookup | Look up multiple errors at once (max 10) | | get_domain_stats | Domain quality metrics and confidence levels | | get_error_chain | Traverse the error transition graph | | report_outcome | Report whether a workaround worked (feeds back into success rates) |

API Endpoints

| Endpoint | Description | |----------|-------------| | /api/v1/match.json | Lightweight regex matching (fits in context window) | | /api/v1/index.json | Full error index with metadata (entries include country field for country canons) | | /api/v1/{id}.json | Individual ErrorCanon | | /api/v1/countries.json | Country index with counts and update dates | | /api/v1/country/{cc}.json | Per-country aggregate (one call returns all entries for that country) | | /api/v1/openapi.json | OpenAPI 3.1 spec | | /api/v1/stats.json | Dataset quality metrics by domain | | /api/v1/errors.ndjson | NDJSON streaming | | /llms.txt | LLM-optimized listing (llmstxt.org) | | /dashboard/ | Data quality dashboard |

Covered Domains (54)

Code error domains (51)

| Domain | Errors | Examples | |--------|--------|----------| | Python | 88 | ModuleNotFoundError, TypeError, KeyError, MemoryError, RecursionError | | Node | 70 | ERRMODULENOTFOUND, EACCES, EADDRINUSE, heap OOM, ERRREQUIRE_ESM | | Docker | 65 | no space left, exec format error, bind address in use, healthcheck | | Kubernetes | 61 | CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC forbidden, HPA | | Git | 60 | failed to push, merge conflicts, detached HEAD, stash apply, tags | | CUDA | 57 | OOM, device-side assert, NCCL, cuDNN, tensor device mismatch | | Go | 54 | nil pointer, unused import, interface conversion, slice out of range | | Java | 54 | NullPointerException, ClassNotFound, OutOfMemoryError, connection pool | | Database | 52 | deadlock, connection pool, slow query, replication lag | | AWS | 51 | AccessDenied, S3 NoSuchBucket, Lambda timeout, CloudFormation rollback | | .NET | 50 | NullReferenceException, LINQ translation, DI circular, EF concurrency | | ROS 2 | 50 | node spin, launch error, QoS mismatch, tf2 transform | | TypeScript | 49 | TS2307, TS2322, TS2345, TS2532, TS7053 | | Rust | 48 | E0382 borrow, E0308 mismatch, E0277 trait, E0106 lifetime | | + 37 more domains | 40+ each | CI/CD, PHP, Terraform, Networking, Next.js, React, pip, Android, ... |

Country-scoped real-world domains (new, growing)

| Domain | Covers | Example dead ends | |--------|--------|-------------------| | visa | Pre-travel authorization, overstay, re-entry bans | ESTA 90-day rule (US), K-ETA (KR), ETIAS/EES (Schengen), Schengen 90/180 (DE) | | banking | Account opening, KYC, foreigner rules | ARC required (KR), residence card 6-month (JP), SSN/ITIN (US) | | emergency | Correct emergency numbers, transit | 112 not 911 (DE), 999/101/111 (UK) | | medical | Insurance, Rx import, coverage | Shaho/Kokuho (JP), NHIS 6-month (KR), EHIC ineligibility (DE), Adderall import ban (JP) | | legal | Criminal liability, contract norms | §86a Nazi symbols (DE), Article 112 (TH), Article 301 (TR), alcohol ban (SA), key money (JP) | | culture | Etiquette, taboos, social norms | Chopsticks in rice (JP), clock gifts (CN), Tiananmen silence, red ink names (KR), bonjour (FR) | | food-safety | Water, pathogens, religious taboos | Tap water (MX), fugu license (JP), beef in India, pork in Indonesia | | communication | Language register, terminology | Honorifics (KR), American War framing (VN), 'gringo' (MX), Cantonese vs Mandarin (HK) | | safety | Driving, public-safety norms | Left-side drive (JP), Autobahn rules (DE), horn-language (IN) |

Data Quality

All metrics are publicly available on the Data Quality Dashboard:

• 2,204 canon entries across 54 domains and 39+ countries
• Benchmark: 90% Precision@1, 95% Precision@3, 0.935 MRR (on code scenarios)
• Error transition graph: 4,330+ edges connecting related errors
• Community feedback loop: report_outcome updates fix success rates from real usage
• Country canons: every entry cites primary gov/embassy/regulator sources,

reviewed by humans (review_status: human_reviewed), no LLM bulk generation

Country coverage (52 countries as of v0.10)

kr · jp · us · de · uk · fr · it · es · nl · ch · pt · ie · at · be · se · no · dk · fi · pl · gr · cn · hk · tw · th · in · vn · id · sg · ph · my · pk · bd · sa · ae · tr · il · ru · br · mx · ar · cl · co · pe · au · nz · eg · ma · et · ng · ke · za · ca

See /country/ hub or /api/v1/countries.json for the authoritative list with counts.

See [docs/country-canon-guide.md](docs/country-canon-guide.md) for the authoring workflow, sourcing requirements, and confidence calibration.

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.

• GitHub 자동 수집 운영안: [docs/GITHUB_DATA_COLLECTION_STRATEGY.md](docs/GITHUBDATACOLLECTION_STRATEGY.md)
• 자동 수집 주기: 6시간마다(하루 4회), 기본 품질 필터: min_score=2
• 수집 데이터는 후보이며, 최종 반영은 maintainer 검수 후 진행

• Submit a new error
• Report a workaround result
• Use report_outcome via MCP after trying a workaround

Development

pip install -e ".[dev]"

python -m generator.pipeline          # Full pipeline
python -m generator.build_site        # Build static site
python -m generator.validate          # Validate data + site
python -m pytest tests/ -v            # Run tests
ruff check generator/ tests/          # Lint
python benchmarks/run_benchmark.py    # Run benchmarks

SEO 점검 가이드 (모든 페이지 공통)

아래 명령은 템플릿에 핵심 SEO 신호가 있는지 빠르게 점검합니다.

python - ` weighted by page strength (country/high-evidence
  pages ranked higher); JSON-LD omits empty dates
- **Style**: em-dash removed site-wide in favor of the hyphen

### v0.9.0 - Country pivot
- **New axis**: country-scoped real-world dead ends alongside code errors
- **56+ country canons** across 20+ countries - visa, banking, legal red
  lines, cultural taboos, food safety, emergency numbers, driving norms
- **3 new domains**: `visa`, `banking`, `emergency` (plus extended use of
  existing `legal`, `culture`, `medical`, `communication`, `food-safety`,
  `safety` domains with country env segment)
- **Per-country landing pages** at `/country/{cc}/` (e.g.
  [/country/jp/](https://deadends.dev/country/jp/))
- **`generator.country_canon_template`** helper for authoring new country
  canons with validated env-segment + audience + jurisdiction metadata
- **`docs/country-canon-guide.md`**: sourcing standards (primary > embassy
  > reputable media), confidence calibration, slug/regex conventions
- Schema unchanged (backward-compatible enum extensions); existing 2,089
  code canons preserved

### v0.8.0
- **Benchmark suite**: 20 error scenarios, Precision@1=90%, MRR=0.935
- **Data quality dashboard** at `/dashboard/` - transparent metrics
- **Outcome feedback loop**: `report_outcome` → aggregated stats → fix_success_rate updates
- **Usage analytics**: anonymous tool usage tracking (domain/match only, no PII)
- **Community contribution**: GitHub Issue templates for new errors and workaround reports
- **TF-IDF search**: improved relevance with smoothed IDF scoring
- **Error transition graph**: materialized graph with 4,330+ edges, hub node analysis
- **9 MCP tools** (added `report_outcome`)

### v0.7.0
- Expanded to **2089 error entries** across **51 domains** (from 1028/20)
- Added 23 new domains
- 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
- SEO fixes for canonical summary URLs

### v0.4.0
- Initial public release with 1028 error entries across 20 domains

## License

MIT (code) · CC BY 4.0 (data)

## Ops Docs

- SEO 운영 가이드: [`docs/SEO_OPERATIONS_GUIDE.md`](docs/SEO_OPERATIONS_GUIDE.md)
- PyPI 릴리즈 매뉴얼: [`docs/PYPI_RELEASE_MANUAL.md`](docs/PYPI_RELEASE_MANUAL.md)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dbwls99706](https://github.com/dbwls99706)
- **Source:** [dbwls99706/deadends.dev](https://github.com/dbwls99706/deadends.dev)
- **License:** MIT
- **Homepage:** https://deadends.dev

Install and usage instructions live in the source repository linked above.