Flisk Troubleshoot

---
name: flisk-troubleshoot
description: 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, TS2688 bun types), Postgres crash loops, services that never turn healthy, "Docker daemon is not responding", `flisk up` or `flisk down` hanging, or a machine overloaded by many containers. Use when something in a running Flisk project is broken or slow. For setup checks before the first `flisk up`, use flisk-doctor; for measuring memory and scale, use flisk-benchmark.
license: MIT
compatibility: Requires the flisk CLI, Docker and Tilt on the local machine. Does not deploy.
metadata:
  author: flisk-sh
  version: "1.0"
---

# 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](https://github.com/flisk-sh/flisk/blob/main/docs/troubleshooting.md).

## First minute: triage

```bash
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.

```bash
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:

  ```bash
  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:

```json
{ "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:

```bash
(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".