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
SIGNUP_DISABLEDSign-ups are currently disabledJoin the waitlist at https://getfloo.com
EMAIL_TAKENEmail already registeredUse floo auth login to sign in

​
Deploy & Build

CodeDescriptionFix
NO_CONFIG_FOUNDNo floo.app.toml or floo.service.toml foundRun floo init to create config files
CONFIG_INVALIDPreflight validation failed (invalid ports, duplicate names)Fix errors and run floo deploy --dry-run to validate
CONFIG_EXISTSConfig files already exist when running floo initUse floo services add to add services instead
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 deploy list
DEPLOY_NOT_FOUNDInvalid deploy IDCheck with floo deploy list
RESTART_FAILEDApp restart failedRun floo logs for details

​
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 doesn’t 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 or floo services rm first
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 deploy

​
Config & 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 0and0 and 1,000,000

​
Billing

CodeDescriptionFix
PLAN_FEATURE_PASSWORDFeature requires a higher planUpgrade at https://app.getfloo.com/settings/billing
PLAN_FEATURE_FLOO_ACCOUNTSFeature requires a higher planUpgrade at https://app.getfloo.com/settings/billing

​
Handling errors in agents

RESULT=$(floo deploy --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)