> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Start from what you see, a failed connect, a failed deploy, a broken app, a domain or sign-in problem, and jump to the fix.

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](https://getfloo.com/docs/reference/error-codes.md).
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](https://getfloo.com/docs/guides/limits.md). |
| `GITHUB_APP_NOT_INSTALLED`, `GITHUB_REPO_NOT_IN_INSTALLATION`, or `GITHUB_INSTALLATION_NOT_AUTHORIZED` | [Which GitHub failure am I looking at?](https://getfloo.com/docs/cli/github.md#which-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](https://getfloo.com/docs/cli/auth.md). |
| `CONFIG_INVALID` or `INVALID_PROJECT_CONFIG` | Run `floo preflight` and fix the key it names. See the [config spec](https://getfloo.com/docs/reference/config-spec.md). |

## A deploy fails

1. Find the deploy and its status:

   ```bash theme={null}
   floo deploys status --app my-app --json
   ```

2. If it failed before going live, read the build log:
   `floo deploys logs <deploy-id> --app my-app`. See [Logs](https://getfloo.com/docs/guides/logs.md#build-logs).

3. If the build passed but the service never became healthy, check the
   [container contract](https://getfloo.com/docs/reference/container-contract.md): listen on `0.0.0.0` and
   `$PORT`, and do not bind `/healthz`.

4. `MISSING_REQUIRED_ENV_VAR` names the variable to set. `SPEND_CAP_EXCEEDED`
   means billing is blocking new deploys; see
   [Billing and spend caps](https://getfloo.com/docs/guides/budget-controls.md).

## 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](https://getfloo.com/docs/guides/logs.md#a-practical-debug-loop). |
| Can't reach the database or Redis | [Postgres: debug a connection issue](https://getfloo.com/docs/guides/postgres.md#debug-a-connection-issue), [Redis: debug a connection issue](https://getfloo.com/docs/guides/redis.md#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](https://getfloo.com/docs/guides/managed-services.md#attach-credentials-to-services). |
| A managed service failed to provision | `floo doctor managed-services --app my-app`. See [doctor](https://getfloo.com/docs/cli/doctor.md). |
| An env var change didn't take effect | Dev: `floo env set ... --restart`. Prod: the next release applies it. See [Environments](https://getfloo.com/docs/guides/environments.md#per-environment-env-vars). |
| The first request after a quiet period is slow | [Scaling and availability](https://getfloo.com/docs/guides/scaling.md) |
| A bad change is live in prod | [Roll back](https://getfloo.com/docs/guides/rollbacks.md) to an earlier deploy |

## Releases, domains, and sign-in

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

## Still stuck

Email [team@getfloo.com](mailto: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](https://getfloo.com/docs/cli/feedback.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.