К основному содержанию
правило CX Codex

troubleshooting — правило для Claude Code: что делает и как установить

Правило troubleshooting с чек-листом для диагностики локального стека Polar: занятые порты, Docker, база данных, MinIO и фронтенд-сборка.

Apache-2.0 ★ 1 216 обновлён 2026-10-24

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings
Открыть на GitHub

Что делает troubleshooting

Правило собирает частые проблемы dev docker окружения в один файл: сервис не стартует, демон Docker не запущен, после смены версии Python в .python-version контейнер api падает на uv sync с ошибкой No interpreter found, первая загрузка не может клонировать git-зависимость. Для каждого случая дана команда диагностики (lsof -i :8000, docker info, dev docker logs) и команда исправления (dev docker up -b --pull -d, docker restart polar-app-<N>-api-1).

Отдельно разобраны проблемы с базой — health check занимает до 40 секунд при первом старте, у каждого инстанса своя база polar_dev_<N> — и с MinIO, где консоль доступна на http://localhost:9001 с кредами polar-development / polar123456789. Если polar-shared-db-1 пересоздали отдельной командой, api и worker держат старые соединения и падают с connection is closed: лечится перезапуском этих контейнеров.

Правило отдельно предупреждает не смешивать dev docker и голый docker compose — они создают параллельные стеки на разных сетях и путают статус контейнеров.

Какие задачи решает

  • найти команду для диагностики упавшего сервиса
  • починить ошибку No interpreter found после обновления Python
  • разобраться, почему первая загрузка не клонирует git-зависимость
  • перезапустить соединения после пересоздания общей базы
  • очистить и пересобрать окружение с нуля

Примеры запросов агенту

  • Сервис api не стартует, проверь логи и порты по правилу troubleshooting
  • api падает с ошибкой No interpreter found, что делать по правилу troubleshooting
  • Как восстановить соединение с базой после dev docker down по правилу troubleshooting

Как установить troubleshooting

1Через маркетплейс плагинов

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings

2Вручную: положить файлы

.claude/rules/troubleshooting.md

Поле paths во frontmatter ограничивает файлы

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы о troubleshooting

Как установить troubleshooting в Claude Code?

Выполните /plugin marketplace add fcakyon/claude-codex-settings, затем /plugin install polar-skills@claude-settings. Правило появится в .claude/rules/troubleshooting.md.

Что делает правило troubleshooting?

Собирает чек-лист диагностики для локального стека Polar на Docker: незапущенный сервис, устаревший образ Python, обрыв клонирования git-зависимости, падение соединений с базой и проблемы MinIO. К каждому случаю даны команды проверки и исправления.

Чем опасно смешивать dev docker и обычный docker compose?

Они создают параллельные стеки на разных Docker-сетях с разными префиксами контейнеров. Память расходуется дважды, docker ps показывает дубли, а docker compose down на одном стеке оставляет второй с разорванными сетевыми связями.

Исходный текст

troubleshooting.md · Apache-2.0
---
title: Troubleshooting Common Issues
category: Debugging
tags: troubleshooting, errors, fixes
---

# Troubleshooting Common Issues

## Service Won't Start

**Check if ports are in use:**
```bash
lsof -i :8000    # API port
lsof -i :3000    # Web port
lsof -i :5432    # Database port
```

**Verify Docker is running:**
```bash
docker info
```

**Check container logs:**
```bash
dev docker logs api
dev docker logs web
```

**Try stop and restart:**
```bash
dev docker down
dev docker up -d
```

## Docker Daemon Not Running

`dev docker up` preflights the daemon and prints a friendly message if it's
down. If you see it, start Docker (OrbStack or Docker Desktop) and retry. A raw
`docker.sock: no such file or directory` from another command means the same
thing.

## `No interpreter found for Python 3.14.x` (stale base image)

The api container exits during the JWKS/`uv sync` step with something like:

```
error: No interpreter found for Python 3.14.6 in managed installations or search path
```

This is a **stale base image**: the cached api image ships an older Python patch
than `server/.python-version` requires, and a plain rebuild reuses the cached
`FROM` layer. Refresh the bases and rebuild:

```bash
dev docker up -b --pull -d
```

`--pull` re-fetches `python:3.14.x-slim` and `uv` so the rebuilt image satisfies
the pin. (The Dockerfile pins the patch to keep this rare, but a `.python-version`
bump can still outrun a cached image.)

## First boot fails cloning a git dependency

`uv sync` clones a git dependency (the dramatiq fork) over the network, and
Docker's embedded DNS can flap transiently:

```
failed to fetch commit ... Could not resolve host: github.com
```

Startup now retries `uv sync` a few times, so this usually self-heals. If the
container still exited, just restart it — the retry runs again with a fresh
resolver:

```bash
dev docker up -d api worker
```

## Database Connection Failed

**Wait for health check (up to 40 seconds on first start)**

**Check db container:**
```bash
dev docker ps
dev docker logs db
```

**Verify database is healthy:**
```bash
# Each instance has its own database: polar_dev_<instance-number>
dev docker exec db psql -U polar -d polar_dev_<N> -c "SELECT 1"
```

Shared infra (db/redis/minio) is on the `polar-shared` Docker network with no
host port — reach it through `dev docker exec` or `docker exec polar-shared-<svc>-1`.

## Hot-Reload Not Working

**Check file mounting:**
```bash
dev docker shell api
ls -la /app/server/polar/
```

**Restart the service:**
```bash
dev docker restart api
```

**If still broken, rebuild:**
```bash
dev docker build api
dev docker restart api
```

## Out of Memory

**Check Docker memory settings** (should be 8GB+)

**Stop unused instances:**
```bash
dev docker down -i 1
dev docker down -i 2
```

**Clean up Docker:**
```bash
docker system prune
```

### `ERR_PNPM_ENOMEM` on first `dev docker up`

On a fresh worktree the api container (building the email renderer) and the
web container (installing frontend deps) can both run `pnpm install` at the
same time and OOM. Symptom in `docker logs polar-app-<N>-api-1`:

```
ERR_PNPM_ENOMEM  ENOMEM: not enough memory, copyfile ...
```

`docker ps` then shows api/web with `Exited (1)` while worker is still `Up`.

**Fix — restart the failed containers, pnpm resumes from its cache:**

```bash
docker start polar-app-<N>-api-1 polar-app-<N>-web-1
```

Wait for `/healthz` on the API port (printed by `dev docker up`) to come up
before continuing. Bumping Docker Desktop's memory above 8 GB or starting
services one at a time (`dev docker up -d api`, then `web`) also avoids the
clash.

## MinIO/S3 Issues

Shared MinIO exposes ports 9000 (API) and 9001 (console) on localhost. Access
the console at http://localhost:9001 with credentials `polar-development` /
`polar123456789`.

**Check minio-setup logs:**
```bash
dev docker logs minio-setup
```

**List this instance's buckets:**
```bash
dev docker exec minio mc alias set local http://localhost:9000 \
  polar-development polar123456789
dev docker exec minio mc ls local
```
Buckets are per-instance: `polar-s3-<N>` and `polar-s3-public-<N>`.

## Frontend Build Errors

**Clear Next.js cache:**
```bash
dev docker shell web
rm -rf .next
exit
dev docker restart web
```

**Reinstall dependencies:**
```bash
dev docker shell web
pnpm install
exit
dev docker restart web
```

## Migration Issues

**Check current migration state:**
```bash
dev docker shell api
uv run alembic current
```

**Run pending migrations:**
```bash
uv run alembic upgrade head
```

**Rollback if needed:**
```bash
uv run alembic downgrade -1
```

## Stale Connections After Shared DB Recycle

If `polar-shared-db-1` was recreated (e.g. you ran `dev docker down` on the
shared stack, or it was replaced by an unrelated `docker compose` run), the
running api/worker still hold connections to the old container and surface
errors like:

```
asyncpg.exceptions._base.InterfaceError: connection is closed
sqlalchemy.dialects.postgresql.asyncpg.InterfaceError
```

**Fix — restart api and worker so the pool reconnects:**

```bash
docker restart polar-app-<N>-api-1 polar-app-<N>-worker-1
```

## Don't Mix `dev docker` and Bare `docker compose`

`dev docker` runs the shared infra under the project name `polar-shared` on
the `polar-shared` network. Running `cd server && docker compose up` from the
same checkout creates a parallel stack on `server_default` with `server-`
prefixed containers. They don't conflict by name, but: they double the
memory footprint, `docker ps` shows two of everything, and a later
`docker compose down` on one stack will leave the other half running with
broken cross-network references.

Pick one. For everything in this skill, prefer `dev docker`.

## Complete Reset

**When all else fails:**
```bash
dev docker cleanup -f
dev docker up -b -d
```

This removes all data and rebuilds from scratch.

## Getting Help

1. Check logs: `dev docker logs`
2. Check status: `dev docker ps`
3. Check Docker: `docker info`
4. Try restart: `dev docker restart`
5. Try cleanup: `dev docker cleanup`

© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings

Похожие правила IDE

Все правила IDE по теме «DevOps и инфраструктура» →
object-storage devops-skills Скилл object-storage для работы с объектным хранилищем: команды AWS CLI, бакет-политики, lifecycle-правила, версионирование и self-hosted MinIO. CX Codex +1 387установок troubleshooting-dbt-job-errors dbt-labs Скилл troubleshooting-dbt-job-errors для Claude Code разбирает сбои dbt Cloud по логам, Admin API, истории коммитов и запросам к данным. Запускается, если сообщение об ошибке не объясняет причину. CX Codex +1 1 100установок go-troubleshooting eduardo-sl Скилл go-troubleshooting для Claude Code ведёт агента по диагностике рантайм-проблем в Go: паники, дедлоки, утечки горутин и памяти, отчёты race detector. Задаёт порядок работы — воспроизвести, наблюдать, локализовать, затем править код. CX Codex +1 ★ 90звёзд репо golang-troubleshooting samber Скилл golang-troubleshooting для Claude Code систематически ищет причины падений, гонок данных и утечек памяти в Go. Помогает воспроизвести баг тестом и разобрать трейс. CX Codex +1 42 300установок troubleshooting-flows celigo Скилл troubleshooting-flows находит причины сбоев, зависаний и частичных ошибок в потоках интеграции Celigo. Помогает разобрать логи и безопасно исправить конфигурацию без случайных повторных записей. CX Codex +1 4 000установок chrome-mcp-troubleshooting trailofbits Скилл chrome-mcp-troubleshooting помогает устранить сбои связи между Chrome и Claude Code на macOS. Скилл находит конфликт сокетов и манифестов между десктопным приложением и консольной утилитой. CX Codex +1 2 900установок

Из того же набора113

Весь набор →
polar-local-environment Скилл polar-local-environment помогает запускать и обслуживать локальное окружение Polar через dev docker. Он пригодится для отладки сервисов и работы с несколькими изолированными worktree. CX Codex +1 ★ 1 216звёзд репо yolo-training Скилл yolo-training диагностирует графики обучения YOLO26 и results.csv, объясняет переобучение и низкий mAP, подсказывает, какой параметр менять. CX Codex +1 ★ 1 216звёзд репо supabase-cli Скилл учит агента управлять проектами через Supabase CLI: поднимать локальный стек, писать миграции, тестировать edge functions и генерировать типы TypeScript. CX Codex +1 ★ 1 216звёзд репо payment-testing Правило payment-testing собирает нюансы локальной проверки входа, Stripe, подписок, возвратов и backoffice. Помогает разобраться, почему тестовый сценарий ведёт себя не так, как ожидалось. CX Codex +1 ★ 1 216звёзд репо supabase-js Скилл снабжает ассистента шпаргалками и синтаксисом официального SDK @supabase/supabase-js: от базовых фильтров PostgREST до загрузки файлов и Edge Functions. CX Codex +1 ★ 1 216звёзд репо create-pr Скилл create-pr для Claude Code готовит pull request для ревью: проверяет ветку и изменения, собирает результаты проверок и публикует PR через gh. CX Codex +1 ★ 1 216звёзд репо electron Скилл для управления десктоп-приложениями на Electron (Slack, VS Code, Discord, Figma, Notion, Spotify) через Chrome DevTools Protocol. CX Codex +1 ★ 1 216звёзд репо pull Команда pull для Claude Code синхронизирует локальную конфигурацию, схему базы и Edge Functions со связанным проектом Supabase. Обновляет локальные данные одной командой. CX Codex +1 ★ 1 216звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой