--json, the error response includes a code field with an UPPER_SNAKE_CASE error code. Use this to handle errors programmatically.
Error response format
{
"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 |
PLAN_FEATURE_ACCOUNTS | Accounts mode requires Pro plan or above | Upgrade at 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 |
SSO_NOT_CONFIGURED | Enterprise SSO is not configured for self-serve use | Contact 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
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) |