Known issues, dated¶
Things the tutorial works around, avoids, or tells you plainly rather than pretending otherwise. Each is dated, because the point of dating them is that they should stop being true.
Why this page exists
A tutorial that quietly steers around a rough edge teaches you a superstition. One that names it teaches you the platform. When one of these is fixed, the step that avoided it changes and this entry gets struck out.
mecca app exec is not covered¶
As of 2026-08. The tutorial never uses it.
That is the largest deliberate omission here, and it shapes the design: every migration runs in the container's start command (step 7) because there is no reliable way to run a one-off command against a deployed app.
The pattern you were given instead — wait for the database, migrate, exec the
server — is better in the ways that matter anyway. It is idempotent, it runs on
every replica, and an app that can bring itself up from nothing needs no operator
present. When exec is dependable, it becomes convenient rather than necessary.
app versions does not exist in this CLI¶
As of 2026-08. Step 14 uses mecca build list instead.
The Python CLI has an app versions subcommand, which lists deployable versions and
marks the live one. The TypeScript CLI — the one this tutorial targets, and the
one published to NPM — does not have it yet.
mecca build list -a <app> shows the same image tags and is what
step 14 tells you to use. It is very slightly worse for the job: it lists
builds rather than successful deploys, so a tag that built and then failed
to deploy also appears, and nothing marks which one is live.
When an app versions subcommand lands here, step 14 should go back to it.
mecca deploy preflight is not ported¶
As of 2026-08. The command exists and refuses.
The tutorial does not teach it. When it lands it belongs near step 13, alongside backups — both are about being sure before you commit.
Path routing is off by default¶
As of 2026-08. Step 15 needs it enabled.
It is a per-environment setting, so your environment may well have it on — try
the step and see. If it refuses, step-14 is a complete working application and
steps 16 and 17 follow from it without loss.
Unknown config keys are dropped in silence¶
As of 2026-08. Step 4 teaches this deliberately.
A misspelled key deploys successfully and does nothing. There is no warning to
search for, which makes it the most expensive small mistake on the platform. It
is being addressed; until it is, the habit of re-reading key names is the
defence, and mecca debug is the tool.
resources.cpu is accepted and ignored¶
As of 2026-08. Named at step 4 so you do not reach for it.
resources.memory is honoured. cpu parses and no part of the platform reads
it.
There are no scheduled backups¶
As of 2026-08. Step 13 says so plainly.
The only automatic backup is the safety copy taken before a restore. If you want one before every schema change, your command takes it.
Rollback is manual¶
As of 2026-08. Step 14 is built around it.
Nothing notices a successful deploy that serves errors. mecca build list plus
mecca deploy --image-tag --no-build is the recovery plan, and it is worth
knowing before you need it.
Tenant API keys¶
As of 2026-08. Not covered, because they do not currently work for tenant
accounts. Some documentation elsewhere suggests otherwise. Use
mecca login and a session.
Deploy hooks¶
As of 2026-08. The route exists; there is no CLI for it and it is undocumented. It is the only CI-driven deploy path today. Mentioned so you know it exists, not taught, because a tutorial cannot promise "it MUST WORK" about a surface with no supported interface.