flisk-troubleshoot
Diagnose a Flisk stack that fails after `flisk up` starts it - red or pending Tilt resources (golden image "pull access denied", run-only "No such image", missing shared-platform-engineering files, TS
SKILL.md.claude/skills/flisk-troubleshoot/SKILL.md
GitHubFlisk troubleshooting
Work from evidence: what the CLI, Tilt and Docker report. Say what you measured, what you estimated and what you do not know, in that order. The full message-by-message guide is docs/troubleshooting.md.
First minute: triage
flisk status --unhealthy --json # which services are failing or still starting
flisk logs --unhealthy --tail 100 # their recent logs
flisk doctor --json # machine and project checks
time docker ps -q | wc -l # how many containers, and how slow Docker is
docker pstaking more than about 5 s means the machine is overloaded, not broken.flisk doctorandflisk downgive up after their own 10 s Docker check in that state. Check load (uptime) and free memory before blaming Docker, Tilt or the code.- A running
tilt uprecreates any container youdocker stopwithin seconds. Runflisk down(it stops this project's Tilt too) instead of stopping containers one by one. - Several Flisk projects can share one Docker daemon. Containers are named
<project>-<stack>-autogenerated-<service>-1; filter by project before stopping anything. - Before anything that runs longer than about 5 minutes or starts dozens of containers, tell the user and give an estimate. Start only the stack you need:
flisk up <stack>, orflisk up <stack> --only <service>.
Symptoms, causes and fixes
"Docker daemon is not responding (docker ps hung for 10s)"
Cause: usually overload, as above. Fix: flisk down, wait for the load to drop, then start one stack instead of all of them.
flisk up keeps waiting, or init-networks is red
Cause: Docker has no free address pools (all predefined address pools have been fully subnetted). Every Flisk project creates several networks and flisk down keeps them. Fix: flisk doctor --fix --scope=machine removes unused networks of every Flisk project. For throwaway projects, stop them with flisk down --prune-networks.
Postgres restarts with "Database is uninitialized and superuser password is not specified"
Cause: the container was created while DB_PASSWORD was empty. Environment variables are fixed when a container is created, so editing .env afterwards does not help.
docker inspect <project>_postgres --format '{{range .Config.Env}}{{println .}}{{end}}' | grep POSTGRES_PASSWORD
Fix: set DB_PASSWORD in the project .env (flisk doctor reports an empty one), then recreate the container with flisk down and flisk up. The data volume survives.
Tilt: pull access denied ... <project>-l4-backend:latest (or -l3-frontend)
The golden image named in the error is missing locally. Check with docker image inspect <project>-l4-backend:latest.
golden-layers-buildis still running: wait for it. Tilt does not retry resources that failed earlier, so trigger every errored resource yourself:tilt get uiresources -o json | python3 -c 'import json,sys; [print(i["metadata"]["name"]) for i in json.load(sys.stdin)["items"] if i.get("status",{}).get("updateStatus")=="error"]' | xargs -n1 tilt triggergolden-layers-buildfinished but the image is missing: a golden target failed, often on a transient package-mirror error. Readtilt logs golden-layers-buildfor the firstERROR: target ...: failed to solve. Runtilt trigger golden-layers-build(orFLISK_GOLDEN_REBUILD=1 flisk upfor a full rebuild), then trigger the errored resources as above. Current versions retry the bake up to 3 times and log "Golden layers build failed after 3 attempts" when all fail.
*-run-only resources fail with No such image: <project>_<stack>_<service>:dev
Cause: they ran before the image was built. Fix: once the image builds, tilt trigger them.
Build context is missing generated files
The build fails with "/shared-platform-engineering/docker-templates/<x>.sh": not found or "/package.json": not found. flisk doctor reports this as Generated Runtime Assets. Fix: run flisk up again (it refreshes these assets before Tilt starts) or flisk config regenerate. If the root package.json is still missing, add a Bun workspace manifest:
{ "name": "<project>", "private": true, "type": "module", "workspaces": ["services/*/*"] }
TS2688: Cannot find type definition file for 'bun'
Cause: the generated tsconfig sets "types": ["bun"] but the service's package.json has no @types/bun. Fix: add @types/bun to its devDependencies. flisk doctor reports this too.
HTTP 404 from Traefik
Traefik is up but has no route for that URL. Use the URLs printed by flisk up or flisk networks; a resource named orders-api is routed at /api/orders on api.<project>.localhost.
Reading Tilt state
- Use the
tiltCLI; the HTTP API atlocalhost:10350/api/viewneeds a session token. tilt get uiresources <name> -o jsonshows one resource.buildHistory[0]is the newest build; reading the last entry shows a stale error.tilt logs <resource>gives the full build log.
Contributors: engine edits have no effect
Projects run a vendored copy of the engine in .flisk/.flisk-out/flisk-cli-ext/, which an installed flisk refreshes from its own bundle. To run your checkout's engine:
(cd <flisk-checkout>/cli && bun run build)
FLISK_EXTENSION_SOURCE=<flisk-checkout> bun <flisk-checkout>/cli/bin/flisk.js project --yes
Guardrails
- Do not hand-edit
.autogenerated/files to make a build pass. Fixservice.jsonor the generator. - Do not stop containers by broad name patterns, and do not kill another project's Tilt.
- Do not polish a proxy metric (image size) when the user's problem is time, CPU or a frozen machine; measure what hurts. For memory and scale numbers, use the flisk-benchmark skill.
- Give short status lines during long builds; silence reads as "nothing works".