> ## 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.

# Error Codes

> All floo CLI error codes with descriptions and troubleshooting.

When a command fails with `--json`, the error response includes a `code` field with an UPPER\_SNAKE\_CASE error code. Use this to handle errors programmatically.

## Error response format

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not logged in. Run `floo auth login` to authenticate.",
    "suggestion": "Run `floo auth login` to authenticate"
  }
}
```

## Error codes

### Authentication

| Code                     | Description                              | Fix                                       |
| ------------------------ | ---------------------------------------- | ----------------------------------------- |
| `NOT_AUTHENTICATED`      | No stored credentials or expired API key | Run `floo auth login`                     |
| `DEVICE_CODE_EXPIRED`    | Device code expired during browser auth  | Run `floo auth login` again               |
| `DEVICE_AUTH_DENIED`     | User denied authorization in browser     | Run `floo auth login` again               |
| `WAITLISTED`             | Account is on the waitlist               | You'll be notified when access is granted |
| `INSUFFICIENT_KEY_SCOPE` | API key doesn't have the required scope  | Use a key with the required scope         |

### Deploy and Build

| Code                           | Description                                                  | Fix                                                                             |
| ------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `NO_CONFIG_FOUND`              | No `floo.app.toml` found                                     | Run `floo init` to create config                                                |
| `CONFIG_INVALID`               | Preflight validation failed (invalid ports, duplicate names) | Fix errors and run `floo preflight` to validate                                 |
| `CONFIG_EXISTS`                | Config files already exist when running `floo init`          | Edit `floo.app.toml` directly to add services                                   |
| `NO_RUNTIME_DETECTED`          | No supported project files found                             | Add `package.json`, `requirements.txt`, `go.mod`, `Dockerfile`, or `index.html` |
| `DEPLOY_FAILED`                | Build or deploy process failed                               | Check `error.message` and build logs                                            |
| `DEPLOY_TIMEOUT`               | Deploy timed out after 10 minutes                            | Check status with `floo deploys list`                                           |
| `DEPLOY_NOT_FOUND`             | Invalid deploy ID                                            | Check with `floo deploys list`                                                  |
| `DEPLOY_IN_PROGRESS`           | Another deploy is already running                            | Wait for it to finish or check `floo deploys list`                              |
| `RESTART_FAILED`               | App restart failed                                           | Run `floo logs` for details                                                     |
| `ROLLBACK_IMAGE_MISSING`       | Rollback target has no stored image                          | Choose a different deploy to rollback to                                        |
| `ROLLBACK_ENVIRONMENT_MISSING` | Rollback target has no environment                           | Deploy first before rolling back                                                |

### Apps

| Code               | Description                               | Fix                                  |
| ------------------ | ----------------------------------------- | ------------------------------------ |
| `APP_NOT_FOUND`    | No app matches the given name or UUID     | Check the name with `floo apps list` |
| `MISSING_APP_NAME` | App name required in non-interactive mode | Provide a name: `floo init my-app`   |

### GitHub

| Code                              | Description                                         | Fix                                                  |
| --------------------------------- | --------------------------------------------------- | ---------------------------------------------------- |
| `GITHUB_APP_NOT_INSTALLED`        | floo GitHub App not installed                       | CLI will open browser to install                     |
| `GITHUB_REPO_NOT_IN_INSTALLATION` | App installed but does not have access to this repo | Open installation settings to add the repo           |
| `GITHUB_ALREADY_CONNECTED`        | App is already connected to a GitHub repo           | Disconnect first: `floo apps github disconnect`      |
| `GITHUB_REPO_NOT_ACCESSIBLE`      | Cannot access the specified repo                    | Ensure the GitHub App is installed on the repo's org |
| `GITHUB_NOT_CONNECTED`            | App is not connected to any GitHub repo             | Connect first: `floo apps github connect owner/repo` |

### Services

| Code                   | Description                              | Fix                                                |
| ---------------------- | ---------------------------------------- | -------------------------------------------------- |
| `SERVICE_NOT_FOUND`    | No service with that name                | Run `floo services list` to see available services |
| `DUPLICATE_SERVICE`    | Service name already exists              | Choose a different name in `floo.app.toml`         |
| `INVALID_SERVICE_NAME` | Service name contains invalid characters | Use lowercase, digits, and hyphens only            |

### Releases

| Code                 | Description                            | Fix                              |
| -------------------- | -------------------------------------- | -------------------------------- |
| `RELEASE_NOT_FOUND`  | No release with that ID                | Check with `floo releases list`  |
| `RELEASE_TAG_EXISTS` | A release with that tag already exists | Use `--tag` with a different tag |
| `NO_DEV_DEPLOY`      | No deploy to promote                   | Deploy first: `floo redeploy`    |

### Config and IO

| Code             | Description                                           | Fix                                              |
| ---------------- | ----------------------------------------------------- | ------------------------------------------------ |
| `INVALID_PATH`   | The deploy path is not a valid directory              | Verify the path exists and is a directory        |
| `INVALID_FORMAT` | Input format is wrong (e.g., `KEY=VALUE` missing `=`) | Check the expected format in the command docs    |
| `CONFIG_ERROR`   | Cannot read or write `~/.floo/config.json`            | Check file permissions (should be `0600`)        |
| `PARSE_ERROR`    | Unexpected API response or invalid input              | May indicate CLI/API mismatch, run `floo update` |
| `FILE_ERROR`     | Cannot read or write a file                           | Check the file path and permissions              |
| `INVALID_ROLE`   | Invalid org member role                               | Valid roles: `admin`, `member`, `viewer`         |
| `INVALID_AMOUNT` | Invalid spend cap amount                              | Use a value between \$0 and \$1,000,000          |

### Billing

| Code                           | Description                                                                | Fix                                                                                             |
| ------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `PLAN_FEATURE_PASSWORD`        | Password mode requires Pro plan or above                                   | Upgrade at [https://app.getfloo.com/settings/billing](https://app.getfloo.com/settings/billing) |
| `PLAN_FEATURE_ACCOUNTS`        | Accounts mode requires Pro plan or above                                   | Upgrade at [https://app.getfloo.com/settings/billing](https://app.getfloo.com/settings/billing) |
| `PLAN_FEATURE_SSO`             | Enterprise SSO is a sales-assisted feature, not a self-serve `access_mode` | Contact [sales@getfloo.com](mailto:sales@getfloo.com)                                           |
| `SSO_NOT_CONFIGURED`           | Enterprise SSO is not configured for self-serve use                        | Contact [sales@getfloo.com](mailto:sales@getfloo.com)                                           |
| `SPEND_CAP_EXCEEDED`           | Monthly spend cap reached, deploys blocked                                 | Raise the cap with `floo billing spend-cap set`                                                 |
| `SPEND_CAP_EXCEEDS_PLAN_LIMIT` | Cap exceeds plan's maximum                                                 | Upgrade to raise your limit                                                                     |

### Logs

| Code                 | Description                   | Fix                                           |
| -------------------- | ----------------------------- | --------------------------------------------- |
| `LOGS_UNAVAILABLE`   | Log service not configured    | Check GCP configuration                       |
| `LOGS_QUERY_ERROR`   | Invalid log query parameters  | Check `--since` format and `--severity` value |
| `LOGS_SERVICE_ERROR` | Cloud Logging backend failure | Retry — transient error                       |

## Handling errors in agents

```bash theme={null}
RESULT=$(floo redeploy --json 2>/dev/null)
SUCCESS=$(echo "$RESULT" | jq -r '.success')

if [ "$SUCCESS" = "true" ]; then
  URL=$(echo "$RESULT" | jq -r '.data.deploy.url')
  echo "Deployed to $URL"
else
  CODE=$(echo "$RESULT" | jq -r '.error.code')
  case "$CODE" in
    NOT_AUTHENTICATED)
      floo auth login --api-key "$FLOO_API_KEY"
      ;;
    NO_CONFIG_FOUND)
      echo "Run 'floo init' first"
      ;;
    DEPLOY_FAILED)
      echo "$RESULT" | jq -r '.error.message'
      ;;
  esac
fi
```

## Exit codes

| Exit code | Meaning                                       |
| --------- | --------------------------------------------- |
| `0`       | Success                                       |
| `1`       | Error (check JSON error response for details) |