Level 6 · In practice

6.2Recurring problems (playbook)

Goal: have a "symptom → causes → actions" playbook for common Docker failures.

Estimated time: 12 min · If you only have 5 min: read “The essentials in 30s” + the diagram.

The essentials in 30 seconds

Diagnose: one symptom = likely causes = a sequence of actions — never fix at random.
Root causes: variables, ports, volumes, forgotten rebuild, healthcheck, permissions, cache, login — 90% of blockers.
Verify: ps, logs, config and proof on a real volume, not just on an isolated run.

Idir's thread — the table taped next to the screen

Idir keeps this table next to his screen in Algiers. Verdict after one quarter: three rows served him most — the Restarting container, the already-allocated port, and data lost after rm. For each one, he ended up applying the sequence (symptom, causes, actions) instead of restarting at random.

Observed symptom, verified causes, actions in order: the reflex holds in three steps.

One reflex per symptom

Most Docker blockers are old classics. Linking each symptom to its likely causes and to a sequence of actions saves precious time.

Symptom	Likely causes	Actions
Container stuck in Restarting	missing -e variable, volume at the wrong path, busy port	compose ps, service logs, fix the file, up -d
port already allocated	squatter (old run), two stacks on the same host port	global docker ps, change the host port (left side)
Data lost after rm	no volume, mount at the wrong path	add a named volume, prove with rm + restart
up ignores the new code	image not rebuilt	up -d --build (or bind in dev)
Database "not ready" at startup	depends_on with no condition, no retry	healthcheck + healthy condition + app retry
Permission denied on volume	root mount, non-root USER with no chown	chown at build / align UID, do not go back to root
Huge image / slow build	COPY . . first, no .dockerignore	dependencies first + .dockerignore + multi-stage
Push denied	no login, name with no namespace, no rights	login, account/image name, rights
down wiped everything	down -v on wanted data	down without -v by default; tested backups + restore

Common misinterpretation: "the table replaces diagnosis". No. The table gives likely causes, not a verdict: observe the symptom, verify the cause (ps, logs, config, paths), then apply the targeted action.

Text version of the diagram (SEO / screen readers / translation): How to use the table: 1) Name the observed symptom (Restarting, allocated port, lost data, up ignoring code, database not ready, permission denied, huge image, push denied, destructive down). 2) Keep the table's likely causes in mind without concluding alone (variables, ports, volumes, rebuild, healthcheck, rights, cache, login). 3) Apply the actions in order (ps, logs, config, targeted fix, rebuild, healthcheck, chown, .dockerignore, login, backup). 4) Fix at the root (the same failure coming back = a design to fix: volumes, healthchecks, tags). Lesson: a recurring failure calls for a setting, not random restarts.

Ready-to-say script — diagnosing without random restarts (30 s)

"My symptom: [Restarting / allocated port / lost data / database not ready]. I check the table's likely cause (ps, logs, config, paths), I apply the targeted action and I prove it (restart, down/up, restore)."

Copy-paste template — Docker diagnosis

docker compose ps
docker compose logs -f api
docker ps -a
docker compose config
docker compose up -d --build

Small business / tight budget

No formal table: one symptom, the likely cause, the action and who proves it, noted down.

SME in Algiers

Fold local realities into the diagnosis: real machine, already-taken ports, known contact person.

Remote / hybrid

Add written traces to the actions: remotely, a logged log and a recorded down/up proof avoid duplicates.

Intercultural

Spell out findings in writing: what seems obvious (which service, which port) is not obvious to everyone.

Caution: Generic reminder: the same failure coming back is not ten incidents — fix the design at the root (volumes, healthchecks, tags) and never destroy wanted volumes (down without -v by default, tested backups).

48h challenge — apply tomorrow

Spot 1 current symptom (Restarting, port, data, database not ready), apply the table row (named symptom + verified cause + targeted action) and prove it.

Section exit checklist

I can link a symptom to its likely causes.
I check ps, logs and config before fixing.
I prove every fix (restart, down/up, restore).

Self-rating 1-5: diagnosis before fixing?systematic proof after fixing?

← Previous : Real-world cases (V3)Next : Best practices & pitfalls (V3) →

Check your understanding

Idir's container loops in Restarting. Which reflex does the table prescribe?

💡

Reflex: diagnose the symptom, identify the cause, apply the targeted action — do not restart at random.