A small project can survive a missing feature. It has a harder time surviving two docs that describe different products. Flisk currently has that problem in public. If you are about to write a tutorial from one page, read this first, then generate the files and believe those.
The binary is the smallest version of the bug. The README says npm install -g @flisk-sh/flisk installs the tdk command. The Helm page and the comparison page use tdk. The feature guide uses flisk. Run tdk --version and flisk --version. Quote the one that exists on your machine. Do not quote both as if they were a style choice.
The database is not allowed to have two default names
The feature guide says the project database is app_dev by default, and that backends use DATABASE_URL. The scope note, read from a scaffolded backend's generated Compose file and .env in Flisk 1.3.86, says one shared Postgres 16 container and one database per stack, named <project>_<stack>, with the password in .env.
Those sentences cannot both be the default. One of them is stale, or they describe different layers and nobody wrote the layer down. Before you put either name in application code, print the URL the container actually received. Then keep that name out of source anyway. The earlier piece in this series is the rule: a local database name is a harness fact, not a constant.
The comparison page also says Flisk provisions NATS. The feature guide's always-on list is proxy and database-management. NATS is real enough to have had a bug: a changelog entry says the focus filter left nats disabled, so a service with the NATS feature retried its broker until someone ran tilt enable nats by hand. "Automatically provisioned" and "disabled until you enable it" are different products. If your service needs a broker, check tilt after up. Do not assume the intro paragraph started it.
Prisma is not a default that is also opt-in
The feature guide shows a backend example with "features": ["prisma"] in the same breath as the default feature list. Later it says Prisma is not enabled by default. Add "prisma" only together with prisma/schema.prisma and the prisma and @prisma/client dependencies. The generated Dockerfile copies prisma/ and runs prisma generate. Without those files, the image fails to build.
That second paragraph is the one to follow. The example is how a tutorial creates a red build and calls the tool broken. Enabling a feature flag is not the same as owning the schema the flag expects.
The same page puts golden_image inside an "optional, disabled by default" snippet and then says golden-image is on by default. The troubleshoot page is clearer about the consequence either way: <project>-l1:latest and the other golden tags are local images. They are not in a registry. A CI job that has not built them cannot build .autogenerated/Dockerfile.app.autogenerated. Turn the feature off only if you know which Dockerfile you are about to own.
Doctor used to lie about a free port
One contradiction already got fixed, which is why the class of bug is worth knowing. tdk doctor checks that host ports 80, 443, and 5432 are free and names what holds them, often a local Postgres. A changelog entry says the check used to bind 0.0.0.0 and 127.0.0.1 at the same time. On Linux the second bind collided with the first, so a free port was reported taken. It now probes them one after the other.
If an old doctor told you port 80 was busy and nothing was listening, that report can be the bug, not the machine. Re-run doctor after updating. On Linux and WSL2 a non-root user still cannot bind port 80, so up may move Traefik to the fallback range and print a URL with a port. That part is not a lie. The printed URL is the URL.
tdk doctor also cannot see a chart. The Helm page says it checks local readiness and service issues, not production configuration. A Docker Desktop window can be open while the engine is not responding. Doctor's own hint, from the L1 troubleshoot page, is to quit Docker Desktop completely, reopen it, and wait until it is running. A whale icon is not a daemon.
What to quote, until the pages agree
| If you are about to write | Quote this | Do not quote this |
|---|---|---|
| The database name | The DATABASE_URL in the generated env for that stack |
app_dev or <project>_<stack> from memory |
| Whether NATS is up |
tilt after up, for that feature |
The comparison intro alone |
| Whether Prisma is on | The features array, plus a schema and the two packages |
A sample manifest labeled "default" |
| Which command to document | The binary --version printed |
Whichever page you had open |
| Whether the chart is valid |
helm lint and helm template on the pinned chart |
tdk doctor or tdk config verify
|
| Whether port 80 is free | A current doctor, then the URL up printed |
A remembered "port taken" from an old binary |
Optional infra has a quieter trap of the same family. Monitoring, ELK, and Debezium are free and off by default. The feature guide marks monitoring and ELK as high resource. Enabling them because the page listed them is how a 16 GB laptop stops being a daily driver. Golden layers are the optional-looking feature that is already on. ELK is the default-looking cost that is not.
The size of a contradiction
None of these are the product. The product is still a manifest, a local stack, and a chart you write yourself. The docs are part of the surface area, though, and an agent will treat the first page it opens as the spec.
When two pages disagree, generate the file or run the command. Then fix the page that lost. A tutorial that picks a side without that check is how the third sentence appears.
Top comments (0)