# troubleshooting

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

- правило · `type=rule` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline · ★ 1216 у репозитория
- Автор: fcakyon
- Лицензия: Apache-2.0 · policy=mirror · начало файла — в конце страницы
- Исходник: https://github.com/fcakyon/claude-codex-settings/tree/HEAD/plugins/polar-skills/skills/polar-local-environment/rules/troubleshooting.md
- Обновлён: 2026-10-24
- Проверка безопасности: автоматическая, 2026-11-16 (текст) — признаков вредоносного кода не нашли.
- HTML: https://affpapa.org/nevibecode/rules/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` — они создают параллельные стеки на разных сетях и путают статус контейнеров.

## Установка

### Claude Code (родная платформа)

1. **Через маркетплейс плагинов**
В чате агента (не в терминале):
```text
/plugin marketplace add fcakyon/claude-codex-settings
```
В чате агента (не в терминале):
```text
/plugin install polar-skills@claude-settings
```

2. **Вручную: положить файлы**
- Файл: `.claude/rules/troubleshooting.md` — Поле paths во frontmatter ограничивает файлы

### Codex

**AGENTS.md**
- Codex читает AGENTS.md: вставьте текст правила туда

### Cursor

**Вручную: положить файлы**
- Файл: `.cursor/rules/troubleshooting.mdc` — Во frontmatter: description, globs, alwaysApply

### GitHub Copilot

**Вручную: положить файлы**
- Файл: `.github/instructions/troubleshooting.instructions.md` — Поле applyTo задаёт, к каким файлам применять

### Windsurf (Devin Desktop)

**Вручную: положить файлы**
- Файл: `.devin/rules/troubleshooting.md`

### Cline

**Вручную: положить файлы**
- Файл: `.clinerules/troubleshooting.md`

Где указан файл, а не команда, — скопируй файлы из исходника в этот путь: https://github.com/fcakyon/claude-codex-settings/tree/HEAD/plugins/polar-skills/skills/polar-local-environment/rules/troubleshooting.md

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

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

## Похожие
- [object-storage](https://affpapa.org/nevibecode/skills/object-storage.md) — скилл · 387 установок
- [troubleshooting-dbt-job-errors](https://affpapa.org/nevibecode/skills/troubleshooting-dbt-job-errors.md) — скилл · 1100 установок
- [go-troubleshooting](https://affpapa.org/nevibecode/skills/go-troubleshooting.md) — скилл · ★ 90 у репозитория
- [golang-troubleshooting](https://affpapa.org/nevibecode/skills/golang-troubleshooting.md) — скилл · 42300 установок
- [troubleshooting-flows](https://affpapa.org/nevibecode/skills/troubleshooting-flows.md) — скилл · 4000 установок
- [chrome-mcp-troubleshooting](https://affpapa.org/nevibecode/skills/chrome-mcp-troubleshooting.md) — скилл · 2900 установок

Из того же набора: [fcakyon/claude-codex-settings](https://affpapa.org/nevibecode/by/fcakyon/claude-codex-settings.md) — 113 карточек

_Часть страницы не вошла по размеру — она есть в HTML-версии._

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md
