Troubleshooting

Start with flitzy status <name>: it names the problem and gives a hint. Then flitzy logs <name> for the app’s own output, or flitzy history <name> <deploy-id> when the build failed.

The deploy times out, or “not ready”

The container runs but doesn’t answer on the expected port. Almost always it listens on localhost or on a fixed port.

app.listen(process.env.PORT || 8080, '0.0.0.0');

Python: uvicorn main:app --host 0.0.0.0 --port $PORT. If the port can’t be changed, deploy with --port <port>.

CrashLoopBackOff

The app exits right after starting, and Kubernetes keeps restarting it with growing pauses. flitzy status shows the exit code and the last lines it printed. Common causes: a missing environment variable, a database that isn’t reachable yet (retry instead of exiting), or a start command that isn’t found.

OOMKilled

The app used more than 512 MiB of memory and was killed (exit code 137). Look at the memory in flitzy status. Ways out: load less into memory, stream large files instead of reading them whole, lower worker counts (gunicorn -w 2), or for Node set NODE_OPTIONS=--max-old-space-size=384.

The build fails

Read the full log: flitzy history <name>, then flitzy history <name> <deploy-id>.

• A file is missing that exists locally: it is probably gitignored, so it wasn’t uploaded. Check with git check-ignore -v <file>.
• exec format error: an image or binary was built for x86. The server is ARM64; use multi-arch base images.
• Upload too large: node_modules, a build folder or large media are part of the upload. Add them to .gitignore.

My data is gone after a deploy

The app wrote into its container. Add a volume and write to $DATA_DIR, or use a database.

403 “belongs to another user”

The app name is taken by another account or organization, or your token belongs to a different one than the app. Check flitzy whoami. Pick another name with --name, or use a token of the owning team.

403 app_limit_reached

Your account or team has as many apps as its plan allows (Free: 3, Pro: 15). Delete one (flitzy rm <name> --yes), deploy into an existing app or upgrade to Pro with flitzy billing upgrade. Redeploys always work.

403 plan_required

Custom domains need the Pro plan.

429 Too Many Requests

You hit a rate limit. The message says which one and when to retry. A loop that polls status very often is the usual cause.

The database stays “starting”

A new database needs about a minute. If it stays like that for several minutes, flitzy db list shows an error with the reason. Contact the platform admin if it doesn’t recover.

The domain doesn’t verify

• Does the CNAME point to <app>.flitzy.app of this app?
• Behind Cloudflare: set the record to DNS only.
• Recently changed: wait for the old record’s TTL.

The agent doesn’t see the tools

Run flitzy whoami in a terminal; if that fails, log in again. Then restart the agent completely. Desktop apps often need absolute paths: see Use with AI agents.