Errors and recovery | Cefense docs

Codes are stable across releases. Match on error.code, never on error.message, and surface remedy to the user: it names the fix.

The shapejson

{
  "schemaVersion": 1,
  "ok": false,
  "command": "reproduced",
  "error": {
    "code": "branch_not_scanned",
    "message": "release/2.4 has not been scanned yet.",
    "remedy": "Run cf scan --repo acme/api --branch release/2.4.",
    "exitCode": 2
  }
}

Access and usage

Code	Exit	What to do
`auth_required`	3	Not signed in. Ask the user to run `cf auth login`, then poll `cf auth status --agent`.
`usage_error`	2	Read `remedy`. It names the flag or argument that was missing or wrong.
`feature_required`	4	The account does not include this. Tell the user, and do not retry.
`organization_required`	2	The account belongs to several teams and the command named none. Run `cf org list --agent`, then pass `--org <slug>` or set `CEFENSE_ORG`.
`organization_not_found`	2	That slug is not a team the account belongs to. Run `cf org list --agent` for the real ones. A slug that does not exist gets the same answer, so read it as neither.
`organization_forbidden`	4	Your role does not allow that action. Report it and stop. Only the user can be given a different role.
`unknown_organization`	2	`cf org use` was given a slug the account does not have. Nothing was stored.
`cancelled`	130	Interrupted. Nothing was completed.

The plan refusing

Code	Exit	What to do
`allowance_exhausted`	4	The period's allowance is spent, so no scan will start. Run `cf plan --agent` for what is left and when it resets.
`repository_limit`	4	The plan covers fewer repositories. Tell the user to disconnect one or move up a plan.
`depth_unavailable`	4	Max depth is not on this plan. Re-run at default depth.
`billing_forbidden`	4	Only an owner or admin may change what the organization pays. `canAdministerBilling` says so in advance.
`no_subscription`	4	Nothing has ever been bought, so there is no billing portal. `cf plan upgrade <plan> --agent` prints a checkout URL for the user.
`plan_unavailable`	4	That plan or seat is not on sale on this deployment. Report it verbatim.
`billing_unavailable`	4	This deployment has no billing configured at all. No flag turns it on.
`invalid_plan`	2	Use `plus`, `pro`, or `max`. `free` is what an organization falls back to, not something to buy.
`invalid_seats`	2	A whole number from 0 to 500, counting seats beyond the ones the plan includes.

See Usage and limits for what each limit is on each plan.

Filters and lookups

Code	Exit	What to do
`invalid_severity`	2	Use `critical`, `high`, `watch`, or `info`.
`invalid_category`	2	Use `code`, `dependency`, `secret`, `misconfig`, or `os-package`.
`finding_not_found`	2	The id is not in the scan being read. List again: ids belong to a scan.
`branch_not_found`	2	No such branch. Run `cf branches --agent`.
`branch_not_scanned`	2	Scan the branch before reading its findings.

Fixes and pull requests

Code	Exit	What to do
`fix_not_found`	2	Generate the patch first.
`fix_not_ready`	2	The patch is not `ready`. Check its status with `cf fix show`.
`fix_in_progress`	2	One is already generating. Poll rather than starting another.
`fix_not_published`	2	Open the pull request before trying to merge it.
`invalid_merge_method`	2	Use `merge`, `squash`, or `rebase`.
`confirmation_required`	2	Ask the user in this conversation, then pass `--yes`.

Refusals from the provider

Code	Exit	What happened
`pull_request_blocked`	4	A required review or status check is pending.
`pull_request_conflicted`	4	The branch conflicts with its base.
`pull_request_draft`	4	The pull request is still a draft.
`pull_request_closed`	4	It was closed without merging.

Settings, exports, and skills

Code	Exit	What to do
`invalid_scan_mode`	2	Use `manual`, `push`, or `scheduled`.
`invalid_scan_interval`	2	Use `1h`, `6h`, `12h`, `24h`, or `168h`.
`invalid_scan_depth`	2	Use `default` or `max`.
`invalid_check`	2	Use `sast`, `sca`, `secrets`, `iac`, `quality`, or `sbom`.
`invalid_format`	2	Use `cyclonedx` or `spdx`.
`sbom_unavailable`	4	Enable the `sbom` check and rescan.
`unknown_target`	2	`cf skill install` was given an agent it does not know. Run `cf skill list`.
`global_unsupported`	2	That agent has no user-wide location. Drop `--global`.
`skill_missing`	4	The bundled skill is absent. Reinstall the package.

Failures

Code	Exit	What to do
`api_error`	4	The API failed. Retry once, then report it.
`internal_error`	4	Unexpected. Report it, with the message.

Retry policy

Have a correction or need help?

Email the docs team