Troubleshooting - floo

Every floo error has a stable code. Find the code in the CLI output, or in detail.code from the API, and look it up in Error codes. If you have a symptom instead of a code, start here.

Setup and connect

What you see	Where to go
`PLAN_REQUIRED` on connect or deploy	Run `floo billing upgrade` and pick a plan. See Plans and limits.
`GITHUB_APP_NOT_INSTALLED`, `GITHUB_REPO_NOT_IN_INSTALLATION`, or `GITHUB_INSTALLATION_NOT_AUTHORIZED`	Which GitHub failure am I looking at?
`NOT_AUTHENTICATED`, or the CLI signs in to the wrong org	`floo auth login`, then `floo orgs switch <slug>`. See auth.
`CONFIG_INVALID` or `INVALID_PROJECT_CONFIG`	Run `floo preflight` and fix the key it names. See the config spec.

A deploy fails

Find the deploy and its status:

floo deploys status --app my-app --json

If it failed before going live, read the build log: floo deploys logs <deploy-id> --app my-app. See Logs.
If the build passed but the service never became healthy, check the container contract: listen on 0.0.0.0 and $PORT, and do not bind /healthz.
MISSING_REQUIRED_ENV_VAR names the variable to set. SPEND_CAP_EXCEEDED means billing is blocking new deploys; see Billing and spend caps.

The app is live but broken

What you see	Where to go
500s or errors in the app	`floo logs query --app my-app --error --since 30m`. See Logs.
Can’t reach the database or Redis	Postgres: debug a connection issue, Redis: debug a connection issue
`DATABASE_URL` or another managed variable is missing	Check `env.managed` on the service; once any service lists `managed`, only listed services get credentials. See Managed services.
A managed service failed to provision	`floo doctor managed-services --app my-app`. See doctor.
An env var change didn’t take effect	Dev: `floo env set ... --restart`. Prod: the next release applies it. See Environments.
The first request after a quiet period is slow	Scaling and availability
A bad change is live in prod	Roll back to an earlier deploy

What you see	Where to go
`PROMOTE_USE_GITHUB_RELEASE`, or a GitHub release never reaches prod	Environments: the flow. The released commit must be live in dev.
A custom domain stays pending or its certificate fails	Custom domains: troubleshooting
Users see a login page on every request, or identity headers are missing	App sign-in: troubleshooting
A preview environment fails or never appears	Preview environments: troubleshooting
A cron job did not run	`floo cron show <name> --app my-app --env prod`. Jobs exist per environment; see Cron jobs.

Still stuck

Email team@getfloo.com with the app, the environment, the deploy ID, and the error code. floo feedback sends a report from the CLI; see feedback.