Skip to main content
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

{
  "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

CodeDescriptionFix
NOT_AUTHENTICATEDNo stored credentials or expired API keyRun floo auth login
DEVICE_CODE_EXPIREDDevice code expired during browser authRun floo auth login again
DEVICE_AUTH_DENIEDUser denied authorization in browserRun floo auth login again
WAITLISTEDAccount is on the waitlistYou’ll be notified when access is granted
INSUFFICIENT_KEY_SCOPEAPI key doesn’t have the required scopeUse a key with the required scope

​
Deploy and Build

CodeDescriptionFix
NO_CONFIG_FOUNDNo floo.app.toml foundRun floo init to create config
CONFIG_INVALIDPreflight validation failed (invalid ports, duplicate names)Fix errors and run floo preflight to validate
CONFIG_EXISTSConfig files already exist when running floo initEdit floo.app.toml directly to add services
NO_RUNTIME_DETECTEDNo supported project files foundAdd package.json, requirements.txt, go.mod, Dockerfile, or index.html
DEPLOY_FAILEDBuild or deploy process failedCheck error.message and build logs
DEPLOY_TIMEOUTDeploy timed out after 10 minutesCheck status with floo deploys list
DEPLOY_NOT_FOUNDInvalid deploy IDCheck with floo deploys list
DEPLOY_IN_PROGRESSAnother deploy is already runningWait for it to finish or check floo deploys list
RESTART_FAILEDApp restart failedRun floo logs for details
ROLLBACK_IMAGE_MISSINGRollback target has no stored imageChoose a different deploy to rollback to
ROLLBACK_ENVIRONMENT_MISSINGRollback target has no environmentDeploy first before rolling back

​
Apps

CodeDescriptionFix
APP_NOT_FOUNDNo app matches the given name or UUIDCheck the name with floo apps list
MISSING_APP_NAMEApp name required in non-interactive modeProvide a name: floo init my-app

​
GitHub

CodeDescriptionFix
GITHUB_APP_NOT_INSTALLEDfloo GitHub App not installedCLI will open browser to install
GITHUB_REPO_NOT_IN_INSTALLATIONApp installed but does not have access to this repoOpen installation settings to add the repo
GITHUB_ALREADY_CONNECTEDApp is already connected to a GitHub repoDisconnect first: floo apps github disconnect
GITHUB_REPO_NOT_ACCESSIBLECannot access the specified repoEnsure the GitHub App is installed on the repo’s org
GITHUB_NOT_CONNECTEDApp is not connected to any GitHub repoConnect first: floo apps github connect owner/repo

​
Services

CodeDescriptionFix
SERVICE_NOT_FOUNDNo service with that nameRun floo services list to see available services
DUPLICATE_SERVICEService name already existsChoose a different name in floo.app.toml
INVALID_SERVICE_NAMEService name contains invalid charactersUse lowercase, digits, and hyphens only

​
Releases

CodeDescriptionFix
RELEASE_NOT_FOUNDNo release with that IDCheck with floo releases list
RELEASE_TAG_EXISTSA release with that tag already existsUse --tag with a different tag
NO_DEV_DEPLOYNo deploy to promoteDeploy first: floo redeploy

​
Config and IO

CodeDescriptionFix
INVALID_PATHThe deploy path is not a valid directoryVerify the path exists and is a directory
INVALID_FORMATInput format is wrong (e.g., KEY=VALUE missing =)Check the expected format in the command docs
CONFIG_ERRORCannot read or write ~/.floo/config.jsonCheck file permissions (should be 0600)
PARSE_ERRORUnexpected API response or invalid inputMay indicate CLI/API mismatch, run floo update
FILE_ERRORCannot read or write a fileCheck the file path and permissions
INVALID_ROLEInvalid org member roleValid roles: admin, member, viewer
INVALID_AMOUNTInvalid spend cap amountUse a value between $0 and $1,000,000

​
Billing

CodeDescriptionFix
PLAN_FEATURE_PASSWORDPassword mode requires Pro plan or aboveUpgrade at https://app.getfloo.com/settings/billing
PLAN_FEATURE_ACCOUNTSAccounts mode requires Pro plan or aboveUpgrade at https://app.getfloo.com/settings/billing
PLAN_FEATURE_SSOSSO requires Enterprise planContact sales@getfloo.com
SSO_NOT_CONFIGUREDSSO is not yet availableContact support for early access
SPEND_CAP_EXCEEDEDMonthly spend cap reached, deploys blockedRaise the cap with floo billing spend-cap set
SPEND_CAP_EXCEEDS_PLAN_LIMITCap exceeds plan’s maximumUpgrade to raise your limit

​
App Auth

CodeDescriptionFix
INVALID_REDIRECT_URIRedirect URI not registered for this appCheck [auth] redirect_uris in floo.app.toml — must match exactly
NO_REDIRECT_URISNo redirect URIs configuredAdd [auth] redirect_uris to floo.app.toml and redeploy
ACCESS_MODE_MISMATCHApp access mode doesn’t support this auth endpointSet access_mode = "accounts"
INVALID_REFRESH_TOKENRefresh token is invalid or expiredStart a new login flow
INVALID_CODEExchange code is invalid or already usedExchange codes are single-use — start a new login flow
RATE_LIMIT_EXCEEDEDToo many token requests from this IPWait and retry

​
Logs

CodeDescriptionFix
LOGS_UNAVAILABLELog service not configuredCheck GCP configuration
LOGS_QUERY_ERRORInvalid log query parametersCheck --since format and --severity value
LOGS_SERVICE_ERRORCloud Logging backend failureRetry — 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 codeMeaning
0Success
1Error (check JSON error response for details)