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

GitHub

Flisk 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 ps taking more than about 5 s means the machine is overloaded, not broken. flisk doctor and flisk down give 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 up recreates any container you docker stop within seconds. Run flisk 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>, or flisk 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-build is 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 trigger
    
  • golden-layers-build finished but the image is missing: a golden target failed, often on a transient package-mirror error. Read tilt logs golden-layers-build for the first ERROR: target ...: failed to solve. Run tilt trigger golden-layers-build (or FLISK_GOLDEN_REBUILD=1 flisk up for 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 tilt CLI; the HTTP API at localhost:10350/api/view needs a session token.
  • tilt get uiresources <name> -o json shows 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. Fix service.json or 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".