Skip to main content
rule CX Codex

troubleshooting — Claude Code rule: what it does, how to install

troubleshooting — a rule covering common failures in a Dockerized Polar dev stack, from stuck ports to stale database connections.

Apache-2.0 ★ 1,216 updated 2026-10-24

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings
Open on GitHub

What troubleshooting does

The rule walks through failure modes of the dev docker setup: a service that won't start, a Docker daemon that isn't running, an api container exiting during uv sync when the cached base image ships an older Python patch than server/.python-version pins, and a first-boot clone of a git dependency failing on DNS. Each entry pairs a check command (lsof -i :8000, docker info, dev docker logs) with a fix (dev docker up -b --pull -d, restarting the affected container).

Database and storage issues get their own sections: the health check can take up to 40 seconds on first start, each instance keeps a separate polar_dev_<N> database, and MinIO's console sits on http://localhost:9001 with the polar-development / polar123456789 credentials. If the shared polar-shared-db-1 container gets recreated outside the normal flow, api and worker keep holding dead connections and throw connection is closed until restarted.

It also flags a conflict: running bare docker compose alongside dev docker spins up a second stack on a separate network, doubling memory use and leaving orphaned containers if one stack gets torn down without the other.

What it helps with

  • find the right command to debug a crashed container
  • fix a stale Python base image breaking uv sync
  • recover from a failed git dependency clone on first boot
  • reconnect api and worker after the shared database gets recreated
  • wipe and rebuild the whole dev environment

Example prompts for the agent

  • The api container keeps exiting, check ports and logs using the troubleshooting rule
  • uv sync fails with No interpreter found, walk through the troubleshooting rule's fix
  • Database connection dropped after a shared db restart, apply the troubleshooting rule

How to install troubleshooting

1Plugin marketplace

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

2Manually: put the files in place

.claude/rules/troubleshooting.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about troubleshooting

How do I install troubleshooting in Claude Code?

Run /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install polar-skills@claude-settings. The rule lands in .claude/rules/troubleshooting.md.

What does the troubleshooting rule do?

It lists fixes for a Dockerized Polar dev stack: services failing to start, outdated Python base images, git clone failures on first boot, dead database connections, and MinIO or frontend build errors, each with the matching diagnostic and repair command.

Why avoid mixing dev docker with plain docker compose?

They spin up separate stacks on different Docker networks with different container prefixes, doubling memory usage. Tearing down one stack with docker compose down leaves the other running with broken cross-network references.

Source text

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

Similar IDE rules

All IDE rules for DevOps and infrastructure →

From the same set113

The whole set →
polar-local-environment The polar-local-environment skill for Claude Code manages Polar’s local Docker setup, including stack operations, service debugging, and separate environments for multiple worktrees. CX Codex +1 ★ 1,216repo stars yolo-training yolo-training reads YOLO26 training curves and results.csv, diagnoses overfitting or poor mAP, and points to the cheapest fix first. CX Codex +1 ★ 1,216repo stars supabase-cli Equips coding agents to run Supabase CLI commands for local environments, schema migrations, edge function deployments, and TypeScript type generation. CX Codex +1 ★ 1,216repo stars payment-testing The payment-testing rule explains local checks for login, Stripe events, subscription renewals, refunds, and the backoffice. Use it when a payment flow behaves differently in your local stack. CX Codex +1 ★ 1,216repo stars supabase-js Adds practical cheat sheets and patterns for @supabase/supabase-js to your AI coding agent, covering Auth, Storage, Edge Functions, and queries. CX Codex +1 ★ 1,216repo stars create-pr The create-pr skill checks a branch, prepares a review-ready pull request, and publishes it with gh. Use it when you want an agent to handle the PR workflow for your changes. CX Codex +1 ★ 1,216repo stars electron Drives Electron desktop apps like Slack, VS Code, Discord, Figma and Spotify over the Chrome DevTools Protocol. CX Codex +1 ★ 1,216repo stars pull The pull command syncs local configuration, database schema, and Edge Functions with a linked Supabase project. Use it to refresh them in one run. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open