{
  "markdown": "# deadends.dev\n\n<!-- mcp-name: dev.deadends/deadends-dev -->\n\n[![Precision@1](https://img.shields.io/badge/Precision%401-90%25-brightgreen)](https://deadends.dev/dashboard/)\n[![MRR](https://img.shields.io/badge/MRR-0.935-brightgreen)](https://deadends.dev/dashboard/)\n[![Entries](https://img.shields.io/badge/entries-2393-blue)](https://deadends.dev)\n[![Domains](https://img.shields.io/badge/domains-54-green)](https://deadends.dev)\n[![Countries](https://img.shields.io/badge/countries-52-orange)](https://deadends.dev/country/)\n[![MCP Tools](https://img.shields.io/badge/MCP_tools-11-purple)](https://smithery.ai/server/deadend/deadends-dev)\n[![PyPI](https://img.shields.io/pypi/v/deadends-dev)](https://pypi.org/project/deadends-dev/)\n[![License](https://img.shields.io/badge/license-MIT%20%2F%20CC%20BY%204.0-lightgrey)](LICENSE)\n\n**Stop AI agents from repeating known failures - in code AND in the real world.**\n\nAI assistants reliably fumble two kinds of problems: known-failed code fixes, and\ncountry-specific real-world rules they've never been exposed to in training.\ndeadends.dev now covers both:\n\n- **Code errors** (2,089 entries, 51 domains): what NOT to try when an agent\n  hits `ModuleNotFoundError`, `CUDA OOM`, `CrashLoopBackOff`, etc.\n- **Country-scoped dead ends** (250+ entries across 52 countries): visa rules\n  (ETA/eVisitor, NZeTA, e-visas, arrival cards), banking requirements, legal red\n  lines (lèse-majesté, §86a, Article 301), cultural taboos (chopsticks in rice,\n  clock gifts in China, red-ink names in Korea), food safety (tap-water safety by\n  country), emergency numbers, driving norms (left-hand traffic), housing\n  contracts - all the friction where a plausible-sounding global answer is wrong\n  locally.\n\n> **Why the expansion?** Coding dead ends are largely solved by a good LLM.\n> Country-specific friction - Japanese hanko requirements, Schengen 90/180\n> math, Ramadan business hours, Saudi alcohol ban, Indian beef taboos - is\n> where generic AI advice breaks hardest. The codebase and schema are\n> identical; the env segment just carries a country code.\n\n> **90% Precision@1** · **0.935 MRR** · [Data Quality Dashboard](https://deadends.dev/dashboard/)\n\n> **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)\n> **Repository:** [https://github.com/dbwls99706/deadends.dev](https://github.com/dbwls99706/deadends.dev)\n\n## Why Use This?\n\n| Without deadends.dev | With deadends.dev |\n|---------------------|-------------------|\n| Agent tries `sudo pip install` → breaks system Python → wastes 3 retries | Agent sees \"dead end: sudo pip - fails 70%\" → skips it immediately |\n| Agent tells user to tip 15% at a Tokyo restaurant | Agent knows tipping is refused in Japan (`culture/tipping-refused/jp`) |\n| Agent drafts a Thai social post referencing King Rama X | Agent stops: Article 112 lèse-majesté risk (`legal/lese-majeste-article-112/th`) |\n| Agent fixes error A, gets confused by error B | Agent knows \"A leads to B 78% of the time\" → handles both |\n| Agent tells unmarried couple to kiss publicly in Dubai | Agent flags UAE public decency law (`legal/unmarried-public-affection/ae`) |\n\n**What makes this different from asking an LLM?**\n- **Deterministic**: Same query → same answer, every time. No hallucination.\n- **Country-scoped**: ID format `{domain}/{slug}/{env}` - env holds the country\n  code (`kr`, `jp`, `us`, `de`...) so the same taboo can be answered\n  differently for different jurisdictions.\n- **Primary-sourced**: Every country canon cites government sites, embassies,\n  or verifiable reporting. No \"based on general knowledge\" answers.\n- **Community-validated**: Fix success rates updated from real outcome reports.\n- **Sub-millisecond**: Local regex matching, no API roundtrip.\n\n### 현실적인 한계 (운영 관점)\n\n- 모든 에러를 다 커버하지는 못합니다. 없는 케이스는 이슈/PR/`report_outcome`로 빠르게 보완합니다.\n- 설명의 깊이보다 **실전 해결 우선**(dead end/workaround 중심)으로 설계되어 있습니다.\n- 신뢰성은 도메인/케이스마다 다를 수 있으므로, 고위험 변경은 공식 문서/벤더 가이드와 교차 검증을 권장합니다.\n\n## Quick Start (30 seconds)\n\n```bash\npip install deadends-dev\ndeadends \"CUDA error: out of memory\"\n```\n\n### MCP Server (Claude Desktop / Cursor)\n\nAdd to `~/.claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"deadend\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp.server\"],\n      \"cwd\": \"/path/to/deadends.dev\"\n    }\n  }\n}\n```\n\nOr install via [Smithery](https://smithery.ai/server/deadend/deadends-dev) (no local setup):\n\n```bash\nnpx -y @smithery/cli@latest install deadend/deadends-dev --client claude\n```\n\n#### MCP `Unauthorized` 빠른 해결 가이드 (사람용)\n\n`deadend: calling \"initialize\": sending \"initialize\": Unauthorized` 에러가 보이면 아래를 **순서대로 그대로 실행/확인**하세요.\n\n1) 로컬 서버 모드인지, 원격(Smithery) 모드인지 하나만 사용\n```bash\n# 로컬 서버 확인 (정상 시 툴 목록이 출력됨)\npython -m mcp.server --help\n```\n\n2) Claude Desktop 설정 파일 점검 (`cwd`는 실제 경로여야 함)\n```bash\ncat ~/.claude/claude_desktop_config.json\n```\n\n3) 로컬 서버 직접 실행 테스트\n```bash\ncd /path/to/deadends.dev\npython -m mcp.server\n```\n\n4) Smithery 모드라면 재설치(토큰/설정 꼬임 복구)\n```bash\nnpx -y @smithery/cli@latest uninstall deadend/deadends-dev --client claude\nnpx -y @smithery/cli@latest install deadend/deadends-dev --client claude\n```\n\n5) 마지막으로 Claude Desktop 완전 재시작\n```bash\n# macOS 예시\nosascript -e 'quit app \"Claude\"'\nopen -a Claude\n```\n\n> 팁: `Unauthorized`는 보통 잘못된 `cwd`, 중복 서버 설정(로컬+원격 동시), 또는 만료된 인증 상태에서 발생합니다.\n\n### Antigravity (Google AI IDE)\n\nAdd as a remote MCP server - no authentication required:\n\n```json\n{\n  \"mcpServers\": {\n    \"deadend\": {\n      \"serverUrl\": \"https://deadends.dev/mcp\",\n      \"type\": \"http\"\n    }\n  }\n}\n```\n\n> **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](https://discuss.ai.google.dev/t/guide-fixing-authentication-for-the-google-developer-knowledge-mcp-server-and-other-cloud-servers-in-antigravity/136601) for general troubleshooting.\n\n### Python SDK\n\n```python\nfrom generator.lookup import lookup, batch_lookup, search\n\n# Single error lookup\nresult = lookup(\"ModuleNotFoundError: No module named 'torch'\")\n\n# What NOT to try (saves tokens and time)\nfor d in result[\"dead_ends\"]:\n    print(f\"AVOID: {d['action']} - fails {int(d['fail_rate']*100)}%\")\n\n# What actually works\nfor w in result[\"workarounds\"]:\n    print(f\"TRY: {w['action']} - works {int(w['success_rate']*100)}%\")\n\n# Batch lookup (multiple errors at once)\nresults = batch_lookup([\"error1\", \"error2\", \"error3\"])\n```\n\n### Example Response\n\n```\n## ModuleNotFoundError: No module named 'X' (Python 3.11+)\nResolvable: true | Fix rate: 0.88\n\n### Dead Ends (DO NOT TRY):\n- pip install X with system Python (fails 70%): venv not activated\n\n### Workarounds (TRY THESE):\n- Create venv, activate, then pip install (works 95%)\n- Use python -m pip install instead of bare pip (works 90%)\n```\n\n## MCP Tools (11)\n\n| Tool | Description |\n|------|-------------|\n| `lookup_error` | Match an error message against 2000+ known patterns |\n| `get_error_detail` | Full canon by ID |\n| `list_error_domains` | All 54 domains with counts |\n| `search_errors` | TF-IDF keyword search across all domains |\n| `list_errors_by_domain` | All errors in a domain |\n| `list_errors_by_country` | All country-scoped dead ends for an ISO alpha-2 code |\n| `get_country_summary` | Country-level summary (entries, fix rate, domain mix) |\n| `batch_lookup` | Look up multiple errors at once (max 10) |\n| `get_domain_stats` | Domain quality metrics and confidence levels |\n| `get_error_chain` | Traverse the error transition graph |\n| `report_outcome` | Report whether a workaround worked (feeds back into success rates) |\n\n## API Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| [`/api/v1/match.json`](https://deadends.dev/api/v1/match.json) | Lightweight regex matching (fits in context window) |\n| [`/api/v1/index.json`](https://deadends.dev/api/v1/index.json) | Full error index with metadata (entries include `country` field for country canons) |\n| [`/api/v1/{id}.json`](https://deadends.dev/api/v1/python/modulenotfounderror/py311-linux.json) | Individual ErrorCanon |\n| [`/api/v1/countries.json`](https://deadends.dev/api/v1/countries.json) | Country index with counts and update dates |\n| [`/api/v1/country/{cc}.json`](https://deadends.dev/api/v1/country/kr.json) | Per-country aggregate (one call returns all entries for that country) |\n| [`/api/v1/openapi.json`](https://deadends.dev/api/v1/openapi.json) | OpenAPI 3.1 spec |\n| [`/api/v1/stats.json`](https://deadends.dev/api/v1/stats.json) | Dataset quality metrics by domain |\n| [`/api/v1/errors.ndjson`](https://deadends.dev/api/v1/errors.ndjson) | NDJSON streaming |\n| [`/llms.txt`](https://deadends.dev/llms.txt) | LLM-optimized listing ([llmstxt.org](https://llmstxt.org)) |\n| [`/dashboard/`](https://deadends.dev/dashboard/) | Data quality dashboard |\n\n## Covered Domains (54)\n\n### Code error domains (51)\n\n| Domain | Errors | Examples |\n|--------|--------|----------|\n| Python | 88 | ModuleNotFoundError, TypeError, KeyError, MemoryError, RecursionError |\n| Node | 70 | ERR_MODULE_NOT_FOUND, EACCES, EADDRINUSE, heap OOM, ERR_REQUIRE_ESM |\n| Docker | 65 | no space left, exec format error, bind address in use, healthcheck |\n| Kubernetes | 61 | CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC forbidden, HPA |\n| Git | 60 | failed to push, merge conflicts, detached HEAD, stash apply, tags |\n| CUDA | 57 | OOM, device-side assert, NCCL, cuDNN, tensor device mismatch |\n| Go | 54 | nil pointer, unused import, interface conversion, slice out of range |\n| Java | 54 | NullPointerException, ClassNotFound, OutOfMemoryError, connection pool |\n| Database | 52 | deadlock, connection pool, slow query, replication lag |\n| AWS | 51 | AccessDenied, S3 NoSuchBucket, Lambda timeout, CloudFormation rollback |\n| .NET | 50 | NullReferenceException, LINQ translation, DI circular, EF concurrency |\n| ROS 2 | 50 | node spin, launch error, QoS mismatch, tf2 transform |\n| TypeScript | 49 | TS2307, TS2322, TS2345, TS2532, TS7053 |\n| Rust | 48 | E0382 borrow, E0308 mismatch, E0277 trait, E0106 lifetime |\n| + 37 more domains | 40+ each | CI/CD, PHP, Terraform, Networking, Next.js, React, pip, Android, ... |\n\n### Country-scoped real-world domains (new, growing)\n\n| Domain | Covers | Example dead ends |\n|--------|--------|-------------------|\n| `visa` | Pre-travel authorization, overstay, re-entry bans | ESTA 90-day rule (US), K-ETA (KR), ETIAS/EES (Schengen), Schengen 90/180 (DE) |\n| `banking` | Account opening, KYC, foreigner rules | ARC required (KR), residence card 6-month (JP), SSN/ITIN (US) |\n| `emergency` | Correct emergency numbers, transit | 112 not 911 (DE), 999/101/111 (UK) |\n| `medical` | Insurance, Rx import, coverage | Shaho/Kokuho (JP), NHIS 6-month (KR), EHIC ineligibility (DE), Adderall import ban (JP) |\n| `legal` | Criminal liability, contract norms | §86a Nazi symbols (DE), Article 112 (TH), Article 301 (TR), alcohol ban (SA), key money (JP) |\n| `culture` | Etiquette, taboos, social norms | Chopsticks in rice (JP), clock gifts (CN), Tiananmen silence, red ink names (KR), bonjour (FR) |\n| `food-safety` | Water, pathogens, religious taboos | Tap water (MX), fugu license (JP), beef in India, pork in Indonesia |\n| `communication` | Language register, terminology | Honorifics (KR), American War framing (VN), 'gringo' (MX), Cantonese vs Mandarin (HK) |\n| `safety` | Driving, public-safety norms | Left-side drive (JP), Autobahn rules (DE), horn-language (IN) |\n\n## Data Quality\n\nAll metrics are publicly available on the [Data Quality Dashboard](https://deadends.dev/dashboard/):\n\n- **2,204** canon entries across **54** domains and **39+** countries\n- **Benchmark**: 90% Precision@1, 95% Precision@3, 0.935 MRR (on code scenarios)\n- **Error transition graph**: 4,330+ edges connecting related errors\n- **Community feedback loop**: `report_outcome` updates fix success rates from real usage\n- **Country canons**: every entry cites primary gov/embassy/regulator sources,\n  reviewed by humans (`review_status: human_reviewed`), no LLM bulk generation\n\n### Country coverage (52 countries as of v0.10)\n\n`kr` · `jp` · `us` · `de` · `uk` · `fr` · `it` · `es` · `nl` · `ch` · `pt` ·\n`ie` · `at` · `be` · `se` · `no` · `dk` · `fi` · `pl` · `gr` · `cn` · `hk` ·\n`tw` · `th` · `in` · `vn` · `id` · `sg` · `ph` · `my` · `pk` · `bd` · `sa` ·\n`ae` · `tr` · `il` · `ru` · `br` · `mx` · `ar` · `cl` · `co` · `pe` · `au` ·\n`nz` · `eg` · `ma` · `et` · `ng` · `ke` · `za` · `ca`\n\nSee [/country/](https://deadends.dev/country/) hub or\n[/api/v1/countries.json](https://deadends.dev/api/v1/countries.json) for the\nauthoritative list with counts.\n\nSee [`docs/country-canon-guide.md`](docs/country-canon-guide.md) for the\nauthoring workflow, sourcing requirements, and confidence calibration.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full details.\n- GitHub 자동 수집 운영안: [`docs/GITHUB_DATA_COLLECTION_STRATEGY.md`](docs/GITHUB_DATA_COLLECTION_STRATEGY.md)\n- 자동 수집 주기: 6시간마다(하루 4회), 기본 품질 필터: `min_score=2`\n- 수집 데이터는 후보이며, 최종 반영은 maintainer 검수 후 진행\n\n- [Submit a new error](https://github.com/dbwls99706/deadends.dev/issues/new?template=new_error.yml)\n- [Report a workaround result](https://github.com/dbwls99706/deadends.dev/issues/new?template=update_workaround.yml)\n- Use `report_outcome` via MCP after trying a workaround\n\n## Development\n\n```bash\npip install -e \".[dev]\"\n\npython -m generator.pipeline          # Full pipeline\npython -m generator.build_site        # Build static site\npython -m generator.validate          # Validate data + site\npython -m pytest tests/ -v            # Run tests\nruff check generator/ tests/          # Lint\npython benchmarks/run_benchmark.py    # Run benchmarks\n```\n\n## SEO 점검 가이드 (모든 페이지 공통)\n\n아래 명령은 템플릿에 핵심 SEO 신호가 있는지 빠르게 점검합니다.\n\n```bash\npython - <<'PY'\nfrom pathlib import Path\nfiles=[\n  'generator/templates/index.html',\n  'generator/templates/domain.html',\n  'generator/templates/error_summary.html',\n  'generator/templates/page.html',\n  'generator/templates/search.html',\n  'generator/templates/dashboard.html',\n]\nrequired=[\n  '<title',\n  'meta name=\"description\"',\n  'meta name=\"robots\"',\n  'link rel=\"canonical\"',\n  'meta property=\"og:title\"',\n  'meta name=\"twitter:card\"',\n]\nfor f in files:\n    txt=Path(f).read_text()\n    missing=[r for r in required if r not in txt]\n    print(f'✅ {f}' if not missing else f'❌ {f} missing: {\", \".join(missing)}')\nPY\n```\n\n실제 빌드 결과물까지 확인하려면:\n```bash\npython -m generator.build_site\npython -m http.server -d public 8080\n```\n\n그 후 브라우저에서 아래를 점검:\n- `view-source:http://localhost:8080/search/`\n- `view-source:http://localhost:8080/dashboard/`\n- canonical / og / twitter / JSON-LD 유효성\n\n## Changelog\n\n### v0.10.0 - Country coverage expansion\n- **250+ country canons across 52 countries** (up from 56 across 20): emergency\n  numbers for nearly every supported country, modern visa gateways (ETA/eVisitor,\n  NZeTA, e-visas, digital arrival cards), medication-import rules, tap-water\n  safety, left-hand-traffic safety, and banking access - all primary-sourced and\n  human-reviewed\n- **By-destination cross-linking**: country summary pages now link to other dead\n  ends for the same country across domains (a \"More dead ends in {country}\"\n  section), strengthening topical internal linking\n- **SEO**: sitemap `<priority>` weighted by page strength (country/high-evidence\n  pages ranked higher); JSON-LD omits empty dates\n- **Style**: em-dash removed site-wide in favor of the hyphen\n\n### v0.9.0 - Country pivot\n- **New axis**: country-scoped real-world dead ends alongside code errors\n- **56+ country canons** across 20+ countries - visa, banking, legal red\n  lines, cultural taboos, food safety, emergency numbers, driving norms\n- **3 new domains**: `visa`, `banking`, `emergency` (plus extended use of\n  existing `legal`, `culture`, `medical`, `communication`, `food-safety`,\n  `safety` domains with country env segment)\n- **Per-country landing pages** at `/country/{cc}/` (e.g.\n  [/country/jp/](https://deadends.dev/country/jp/))\n- **`generator.country_canon_template`** helper for authoring new country\n  canons with validated env-segment + audience + jurisdiction metadata\n- **`docs/country-canon-guide.md`**: sourcing standards (primary > embassy\n  > reputable media), confidence calibration, slug/regex conventions\n- Schema unchanged (backward-compatible enum extensions); existing 2,089\n  code canons preserved\n\n### v0.8.0\n- **Benchmark suite**: 20 error scenarios, Precision@1=90%, MRR=0.935\n- **Data quality dashboard** at `/dashboard/` - transparent metrics\n- **Outcome feedback loop**: `report_outcome` → aggregated stats → fix_success_rate updates\n- **Usage analytics**: anonymous tool usage tracking (domain/match only, no PII)\n- **Community contribution**: GitHub Issue templates for new errors and workaround reports\n- **TF-IDF search**: improved relevance with smoothed IDF scoring\n- **Error transition graph**: materialized graph with 4,330+ edges, hub node analysis\n- **9 MCP tools** (added `report_outcome`)\n\n### v0.7.0\n- Expanded to **2089 error entries** across **51 domains** (from 1028/20)\n- Added 23 new domains\n- Fixed 73 regex patterns that didn't match their own signatures\n\n### v0.5.0\n- `page_url` field added to index.json, errors.ndjson, and all SDK/MCP responses\n- SEO fixes for canonical summary URLs\n\n### v0.4.0\n- Initial public release with 1028 error entries across 20 domains\n\n## License\n\nMIT (code) · CC BY 4.0 (data)\n\n## Ops Docs\n\n- SEO 운영 가이드: [`docs/SEO_OPERATIONS_GUIDE.md`](docs/SEO_OPERATIONS_GUIDE.md)\n- PyPI 릴리즈 매뉴얼: [`docs/PYPI_RELEASE_MANUAL.md`](docs/PYPI_RELEASE_MANUAL.md)\n\n<!-- mcp-name: io.github.dbwls99706/deadends-dev -->\n",
  "bytes": 17856,
  "sha": "2494a2bf7d235193e92ec05bfe3d46733b1c88fbfce739d4c50d7566ad3f7140",
  "repo_slug": "dbwls99706/deadend.dev",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dbwls99706_deadends_dev_dcc0d004/readme"
}