When it breaks¶

Every If it didn't work table from the tutorial, on one page, arranged by what you are looking at rather than by which step you were on.

Start here, always¶

mecca queue diagnose <action-id>

It answers "why has this not finished" in plain sentences. If you learn one command from this tutorial, learn this one.

mecca debug <app> -b <branch>

One dump: configured variables, recent errors, service health, resolved URLs, and what the container actually received. When something you configured is not happening, this is where its absence becomes visible.

Which log?¶

Question	Command
Did the code compile?	`mecca logs <app> --type build`
Did the platform ship it?	`mecca logs <app> --type deploy`
What did my app print?	`mecca logs <app> --type container --service <name>`

If the version never went live, it is build or deploy. If it went live and misbehaves, it is container.

By symptom¶

Nothing happens when I deploy¶

	Usually
The change is not on the remote	`git status` — the platform builds from the remote, not your disk
You changed a different branch	`-b`, everywhere
The key name is misspelled	Unknown keys are dropped silently. Read them character by character
An overlay is winning	The dashboard's raw-config editor outranks your repo. Clear it

The deploy failed¶

	Usually
Fails after ~2 minutes	Health check. Wrong `port`, or not bound to `0.0.0.0`
Container starts then exits	Read `--type container`; the crash is there
Fails only sometimes	Slow start. Raise `health_check.startup_timeout` (default 120)
Refused before it started	`mecca queue diagnose`. Often the database connection budget
Killed for memory	Raise `resources.memory`

Your site is still up. A failed deploy never replaces a working one.

The deploy succeeded and the app is broken¶

The health check proves the process is up, never that the app is right.

mecca build list -a <app>
mecca deploy <app> --image-tag <good-tag> --no-build -b <branch>

--no-build is what makes it fast and what makes it safe: nothing compiles, so nothing that broke the last build can break this one. Rollback is manual — nothing does it for you.

I cannot see my change¶

	Usually
Some people see it, some do not	Edge cache. `mecca cache invalidate <app>`
Nobody sees it	The deploy did not land. `mecca queue list`
It reverted on the next deploy	`mecca var set` outranks the YAML. `mecca var unset`

A variable is missing or wrong¶

mecca var list <app> -b <branch>
mecca debug <app> -b <branch>

	Usually
Not there at all	Typo in the key, or the block is on a different service
Not what the YAML says	An override. `mecca var unset`
Appeared on the wrong branch	`mecca var set` without `-b` writes to every branch

It works locally and not deployed¶

	Usually
Localhost	Nothing else is on your container's localhost. Use the injected variables
A file it wrote is gone	A container's own filesystem does not survive a deploy. Use a drive
Slower far away	`cdn.coverage` — the default has no African, Asian or South American edge
Two services cannot talk	`${service:name:internal}`

Data¶

	Usually
The database is empty	A branch is a separate app with a separate database
Restore did nothing visible	The bundle post-dates the change. `mecca app backups`
Nothing to restore	Bundles are per branch

Two things nothing does for you¶

There are no scheduled backups. Only the safety copy taken before a restore is automatic.
There is no automatic rollback. A green deploy that serves errors stays until you replace it.

Commands worth keeping¶

mecca queue diagnose <id>       # why is this stuck
mecca debug <app>               # everything about this app at once
mecca build list -a <app>       # what can I roll back to
mecca logs <app> --type build   # did it compile
mecca var list <app> -b <br>    # what is set, and from where
mecca cache invalidate <app>    # is it just the cache