CloudBurn uses consistent exit codes so you can integrate its output into CI/CD pipelines, shell scripts, and quality gates.
Exit codes
| Code | Constant | Meaning |
|---|---|---|
0 | EXIT_CODE_OK | Scan completed successfully with no active findings, or no policy gate was passed |
1 | EXIT_CODE_POLICY_VIOLATION | An active finding satisfies --exit-code or --fail-on (or its iac.fail-on / discovery.fail-on config equivalent) |
2 | EXIT_CODE_RUNTIME_ERROR | Runtime error or usage error — credentials missing, path not found, config invalid, discovery deadline expired, unknown option, invalid option argument, etc. |
Suppressed findings (from inline cloudburn-ignore comments) never trigger EXIT_CODE_POLICY_VIOLATION, even when --exit-code or --fail-on is set. See Suppressing findings inline.
When to use --exit-code
By default, CloudBurn exits 0 even when it finds issues. This lets you use CloudBurn for informational scans without breaking your build.
Pass --exit-code when you want CloudBurn to act as a quality gate — for example, to block a pull request if cost issues are found:
cloudburn scan --exit-code
cloudburn discover --exit-code
Gating on severity with --fail-on
--exit-code fails on any active finding. Use --fail-on high|medium|low instead when you only want CI to fail above a specific severity — for example, to report low-severity findings without blocking the pipeline:
cloudburn scan --fail-on high
cloudburn discover --fail-on high
--fail-on takes priority over --exit-code when both are passed. The same threshold can be set as iac.fail-on or discovery.fail-on in .cloudburn.yml — see Configuration.
CI example
- name: Run CloudBurn scan
run: cloudburn scan --exit-code
This step fails the CI job if any findings are returned. To allow the pipeline to continue and just report findings, omit --exit-code.
Error output format
Runtime errors caught by scan, discover, and config write a JSON error object to stderr and exit with code 2:
{
"error": {
"code": "RUNTIME_ERROR",
"message": "Config file not found: /path/to/.cloudburn.yml"
}
}
code is one of:
| Code | Meaning |
|---|---|
CREDENTIALS_ERROR | AWS credentials are missing or expired |
ACCESS_DENIED | The identity lacks a permission the scan needs |
PATH_NOT_FOUND | A scan path does not exist (a missing --config file is a RUNTIME_ERROR) |
RESOURCE_EXPLORER_NOT_ENABLED | Resource Explorer has not been set up in the account |
RESOURCE_EXPLORER_REGION_NOT_ENABLED | The requested region has no Resource Explorer index |
RESOURCE_EXPLORER_AGGREGATOR_REQUIRED | The run needs an aggregator index, and the account has none reachable |
RESOURCE_EXPLORER_DEFAULT_VIEW_REQUIRED | The aggregator region has no default view |
RESOURCE_EXPLORER_FILTERED_VIEW_UNSUPPORTED | The default view is filtered, so it cannot back a complete scan |
RESOURCE_EXPLORER_TAGS_VIEW_REQUIRED | The view does not include tags, which the tagging rule needs |
RESOURCE_EXPLORER_AGGREGATOR_SWITCH_REQUIRES_DELAY | AWS enforces a 24-hour wait before promoting another aggregator |
INVALID_AWS_REGION | The AWS region resolved during execution is not supported |
INVALID_RESOURCE_EXPLORER_RESOURCE_TYPE | A requested resource type is not supported by Resource Explorer |
RUNTIME_ERROR | Other caught errors, including invalid config and an expired discovery deadline |
Messages are sanitized before they are written: instance metadata hosts, URL credentials, bearer tokens, and signature query parameters are redacted.
Command-line parsing errors, such as an unknown flag or an invalid --region, --format, or --timeout value, also exit with code 2, but write plain-text error and help output to stderr. Do not assume every exit-code 2 response is JSON.
Redirect stderr separately if you need to handle errors differently from findings:
cloudburn --format json scan --exit-code ./iac 2>error.json
What's next
| CI/CD Integration | Full GitHub Actions and GitLab CI pipeline examples |
| Output Formats | Use JSON output for structured error handling |
| cloudburn scan | All scan flags including --exit-code |