Kane CLI Error & Result Codes Reference

Every Kane CLI run ends with a result_code in the run_end event. This page lists every code, explains what triggered it, and tells you what to do next.

result_code explains why a run stopped. The process exit code (0 to 3) is what gates CI. An early refusal can exit without a run_end event, so always check the process exit code too. See Process Exit Codes.

How to Read Result Codes

Result codes follow HTTP-style groupings:

Range	Category	Meaning
1xx	Success	The objective completed successfully.
2xx	Cancelled	The run was cancelled before completion.
3xx	Stuck	The agent could not make further progress.
4xx	Agent Error	An internal agent failure prevented completion.
5xx	Infra Error	A platform or infrastructure issue stopped the run.
6xx	Blocker	An external obstacle (CAPTCHA, paywall, etc.) blocked the agent.
7xx	Assertion Error	The objective’s assertions or checkpoints failed.

The run_end event includes both result_code (numeric) and reason_code (descriptive string):

{
  "type": "run_end",
  "status": "failed",
  "result_code": 310,
  "reason_code": "stuck.max_steps",
  "summary": "Agent reached maximum step limit..."
}

1xx: Success

100 COMPLETE

Field	Value
Reason code	`success.complete`
Status	`COMPLETE`
What happened	All checkpoints passed and the agent confirmed the objective is achieved.
Action	None required.

2xx: Cancelled

200 USER_CANCELLED

Field	Value
Reason code	`cancelled.user`
Status	`CANCELLED`
What happened	The caller cancelled the run (for example, with Ctrl+C, a `cancel` event, or API cancellation).
Action	No action required. Re-run the objective if needed.

3xx: Stuck

The agent reached a dead end. These are not crashes: the agent recognized that it could not make further progress.

310 MAX_STEPS

Field	Value
Reason code	`stuck.max_steps`
Status	`STUCK`
What happened	The agent exceeded the configured `--max-steps` limit before completing the objective.
Action	Increase `--max-steps` (e.g., `--max-steps 60`), or break the objective into smaller, sequential runs.

320 DAG_CYCLE

Field	Value
Reason code	`stuck.dag_cycle`
Status	`STUCK`
What happened	The agent detected 3 repeated page-state cycles (it keeps returning to the same state after each action).
Action	Rephrase the objective with a different approach. The current path leads to a loop, so try an alternative navigation route or add explicit intermediate steps.

330 AP_STUCK

Field	Value
Reason code	`stuck.ap_stuck`
Status	`STUCK`
What happened	The action planner determined there are no viable actions available on the current page to progress toward the objective.
Action	Manual intervention is needed. Check the screenshot at `{session_id}/runs/{run_dir}/run-test/screenshots/` to understand what page state the agent ended on. You may need to adjust the objective, provide credentials, or navigate to a different starting URL.

4xx: Agent Error

An internal agent component failed. These typically indicate a transient issue or a problem with the session state.

410 AP_NO_ACTION

Field	Value
Reason code	`agent_error.ap_no_action`
Status	`ERROR`
What happened	The action planner returned 3 consecutive empty decisions (no action selected).
Action	Retry the run. If the error persists, simplify the objective or file a bug report.

420 REASONING_FAILURE

Field	Value
Reason code	`agent_error.reasoning_failure`
Status	`ERROR`
What happened	An unhandled exception occurred in the reasoning engine.
Action	Check `{session_id}/runs/{run_dir}/run.log` for the full stack trace. Retry the run, because this is usually transient. If it persists, file a bug report with the log file.

430 CLEAN_START_INVALID

Field	Value
Reason code	`agent_error.clean_start_invalid`
Status	`ERROR`
What happened	The `clean_start` validation failed: the agent could not establish a valid initial session state (e.g., the starting URL did not load, or the browser context is corrupted).
Action	Verify the `--url` is accessible and loads correctly. If using `--cdp-endpoint`, ensure the browser is in a clean state.

440 CHILD_FAILED

Field	Value
Reason code	`agent_error.child_failed`
Status	`ERROR`
What happened	A child agent (spawned for a sub-objective during analysis) failed. The parent run cannot continue.
Action	Check the `child_agent_end` event in the NDJSON output for the child’s failure details. Fix the child objective, then re-run the parent.

5xx: Infra Error

Platform or infrastructure failures. These are independent of the objective itself.

510 SCREENSHOT_FAILED

Field	Value
Reason code	`infra_error.screenshot_failed`
Status	`ERROR`
What happened	The browser failed to capture a screenshot (Playwright exception). The agent cannot proceed without visual input.
Action	Check that the browser is still running. If using `--cdp-endpoint`, verify the connection is alive. Restart the browser and retry.

520 BROWSER_CRASHED

Field	Value
Reason code	`infra_error.browser_crashed`
Status	`ERROR`
What happened	The browser process crashed or became unresponsive.
Action	Restart the browser and retry the run. If this happens repeatedly, check available system memory and ensure no other processes are competing for resources.

530 TIMEOUT

Field	Value
Reason code	`infra_error.timeout`
Status	`ERROR`
What happened	The run exceeded its configured timeout.
Action	Increase `--timeout` (in seconds): `--timeout 300`. If the objective is complex, break it into smaller runs.

540 EVENT_DISPATCH

Field	Value
Reason code	`infra_error.event_dispatch`
Status	`ERROR`
What happened	A custom event dispatch (e.g., browser event injection) failed.
Action	Check `{session_id}/runs/{run_dir}/run.log` for the failing event handler. This usually indicates a page script error or an incompatible browser state. Retry the run, and if it persists, file a bug report.

550 CONTROLLER_AUTH

Field	Value
Reason code	`infra_error.controller_auth`
Status	`ERROR`
What happened	The controller returned a `401 Unauthorized` response. Your authentication token has expired or is invalid.
Action	Refresh your authentication token:

kane-cli login
# or re-run login with basic auth
kane-cli login --username "YOUR_LT_USERNAME" --access-key "YOUR_LT_ACCESS_KEY"

Verify with kane-cli whoami, then retry the run.

560 CREDITS_EXHAUSTED

Field	Value
Reason code	`infra_error.credits_exhausted`
Status	`ERROR`
What happened	The controller returned a `402 Payment Required` response. Your account has no remaining credits for AI agent runs.
Action	Purchase additional credits or upgrade your plan on the billing page. Contact your account administrator if you are on a team plan.

6xx: Blocker

An external obstacle on the target website prevented the agent from completing the objective. These are not agent bugs: they require changes to the environment or objective.

610 CAPTCHA

Field	Value
Reason code	`blocker.captcha`
Status	`ERROR`
What happened	The page presented a CAPTCHA challenge that the agent cannot solve.
Action	Solve the CAPTCHA manually in an interactive session first, then re-run. Alternatively, use a test environment that has CAPTCHAs disabled, or allowlist the test IP.

620 PAYWALL

Field	Value
Reason code	`blocker.paywall`
Status	`ERROR`
What happened	The page requires a paid subscription to access the content the objective needs.
Action	Provide credentials for a subscribed account via variables, or test against a non-paywalled environment.

640 BLOCKED

Field	Value
Reason code	`blocker.blocked`
Status	`ERROR`
What happened	The target site blocked access (IP ban, WAF rule, geo-restriction, or bot detection).
Action	Use a different IP address, allowlist the test IP on the target site, or use a different test account. Check whether the site has bot-detection that needs to be configured for testing.

650 ERROR_PAGE

Field	Value
Reason code	`blocker.error_page`
Status	`ERROR`
What happened	The page returned an HTTP error (404 Not Found, 500 Internal Server Error, etc.) instead of the expected content.
Action	Verify the `--url` is correct and the target site is operational. Check `{session_id}/runs/{run_dir}/run-test/screenshots/` to see the error page.

660 AUTH_NO_CREDENTIALS

Field	Value
Reason code	`blocker.auth_no_credentials`
Status	`ERROR`
What happened	The agent encountered a login page but no credentials were provided in the objective or variables.
Action	Provide login credentials using variables:

kane-cli run "Log in and navigate to dashboard" \
  --url https://myapp.com/login \
  --variables '{"username": {"value": "test@example.com"}, "password": {"value": "s3cret", "secret": true}}' \
  --agent

7xx: Assertion Error

The agent completed its actions but one or more assertions or checkpoints did not pass.

710 FINAL_VERIFICATION

Field	Value
Reason code	`assertion_error.final_verification`
Status	`ASSERTION_ERROR`
What happened	The final checkpoint failed. The agent performed all actions but the end state did not match the expected outcome.
Action	This means the objective was not achieved. Review the screenshot at `{session_id}/runs/{run_dir}/run-test/screenshots/` to see the final page state. The objective itself may need adjustment, or the application under test may have a bug.

720 CHECKPOINT_FAILED

Field	Value
Reason code	`assertion_error.checkpoint_failed`
Status	`ASSERTION_ERROR`
What happened	An inline checkpoint (mid-run assertion) failed. The agent detected that an intermediate condition was not met.
Action	Check which checkpoint failed in the step logs at `{session_id}/runs/{run_dir}/run-test/step_N.json`. The assertion condition may be too strict, or the application did not reach the expected state at that point.

730 NO_BRANCH_MATCHED

Field	Value
Reason code	`assertion_error.no_branch_matched`
Status	`ASSERTION_ERROR`
What happened	An if-else objective had multiple branches, but none of the conditions matched the actual page state.
Action	Review your branching conditions. Add a fallback branch, or check the screenshot to see what state the page was actually in. Adjust conditions to cover the observed state.

Quick Lookup Table

Code	Name	Reason Code	Action
100	COMPLETE	`success.complete`	Done
200	USER_CANCELLED	`cancelled.user`	Re-run if needed
310	MAX_STEPS	`stuck.max_steps`	Increase `--max-steps` or simplify
320	DAG_CYCLE	`stuck.dag_cycle`	Try a different approach
330	AP_STUCK	`stuck.ap_stuck`	Manual intervention needed
410	AP_NO_ACTION	`agent_error.ap_no_action`	Retry the run
420	REASONING_FAILURE	`agent_error.reasoning_failure`	Check logs, retry
430	CLEAN_START_INVALID	`agent_error.clean_start_invalid`	Fix session state
440	CHILD_FAILED	`agent_error.child_failed`	Check child agent details
510	SCREENSHOT_FAILED	`infra_error.screenshot_failed`	Check browser
520	BROWSER_CRASHED	`infra_error.browser_crashed`	Restart browser
530	TIMEOUT	`infra_error.timeout`	Increase `--timeout`
540	EVENT_DISPATCH	`infra_error.event_dispatch`	Check event handler
550	CONTROLLER_AUTH	`infra_error.controller_auth`	Run `kane-cli login`
560	CREDITS_EXHAUSTED	`infra_error.credits_exhausted`	Purchase credits
610	CAPTCHA	`blocker.captcha`	Solve manually or disable
620	PAYWALL	`blocker.paywall`	Provide subscription
640	BLOCKED	`blocker.blocked`	Change IP or account
650	ERROR_PAGE	`blocker.error_page`	Fix the URL
660	AUTH_NO_CREDENTIALS	`blocker.auth_no_credentials`	Provide credentials
710	FINAL_VERIFICATION	`assertion_error.final_verification`	Objective not achieved
720	CHECKPOINT_FAILED	`assertion_error.checkpoint_failed`	Check assertion condition
730	NO_BRANCH_MATCHED	`assertion_error.no_branch_matched`	Update branch conditions

Process Exit Codes

kane-cli run exits with one of these codes. Use them to gate downstream CI steps.

Code	Meaning
`0`	Run passed
`1`	Run failed (agent reached an unrecoverable failure, or the upload failed)
`2`	Error (auth, TMS credential exchange, configuration, Chrome, unknown subcommand, or unhandled exception)
`3`	Run was cancelled or hit the `--timeout`

An unresolved-variable warning (code: "unresolved_variables") does not change the exit code. A step that fails on the literal {{name}} text still fails the run.
Under run --analyzer-only, exit 0 means all conditions were judged, not that all are true. Exit 1 means a result was missing, and 3 means cancelled.
testmd run, testrun run, generate and the assurance commands have their own exit code tables. See CLI Reference: Exit Codes.

Handling Errors in Agent Mode

When consuming Kane CLI output programmatically, use result_code ranges to determine your next action:

# Run and capture the result
RESULT=$(kane-cli run "..." --agent --headless 2>/dev/null | tail -1)
CODE=$(echo "$RESULT" | jq -r '.result_code')

case $CODE in
  100) echo "Passed" ;;
  2*) echo "Cancelled" ;;
  3*) echo "Stuck: $(echo $RESULT | jq -r '.reason_code')" ;;
  4*) echo "Agent error: retry recommended" ;;
  5*) echo "Infra error: check environment" ;;
  6*) echo "Blocked: manual intervention needed" ;;
  7*) echo "Assertion failed: check test conditions" ;;
esac

Agent Mode: NDJSON output format and event schema
Troubleshooting: Common issues and fixes
CLI Reference: Full flag and command reference

​How to Read Result Codes

​1xx: Success

​100 COMPLETE

​2xx: Cancelled

​200 USER_CANCELLED

​3xx: Stuck

​310 MAX_STEPS

​320 DAG_CYCLE

​330 AP_STUCK

​4xx: Agent Error

​410 AP_NO_ACTION

​420 REASONING_FAILURE

​430 CLEAN_START_INVALID

​440 CHILD_FAILED

​5xx: Infra Error

​510 SCREENSHOT_FAILED

​520 BROWSER_CRASHED

​530 TIMEOUT

​540 EVENT_DISPATCH

​550 CONTROLLER_AUTH

​560 CREDITS_EXHAUSTED

​6xx: Blocker

​610 CAPTCHA

​620 PAYWALL

​640 BLOCKED

​650 ERROR_PAGE

​660 AUTH_NO_CREDENTIALS

​7xx: Assertion Error

​710 FINAL_VERIFICATION

​720 CHECKPOINT_FAILED

​730 NO_BRANCH_MATCHED

​Quick Lookup Table

​Process Exit Codes

​Handling Errors in Agent Mode

​Related Resources

How to Read Result Codes

1xx: Success

100 COMPLETE

2xx: Cancelled

200 USER_CANCELLED

3xx: Stuck

310 MAX_STEPS

320 DAG_CYCLE

330 AP_STUCK

4xx: Agent Error

410 AP_NO_ACTION

420 REASONING_FAILURE

430 CLEAN_START_INVALID

440 CHILD_FAILED

5xx: Infra Error

510 SCREENSHOT_FAILED

520 BROWSER_CRASHED

530 TIMEOUT

540 EVENT_DISPATCH

550 CONTROLLER_AUTH

560 CREDITS_EXHAUSTED

6xx: Blocker

610 CAPTCHA

620 PAYWALL

640 BLOCKED

650 ERROR_PAGE

660 AUTH_NO_CREDENTIALS

7xx: Assertion Error

710 FINAL_VERIFICATION

720 CHECKPOINT_FAILED

730 NO_BRANCH_MATCHED

Quick Lookup Table

Process Exit Codes

Handling Errors in Agent Mode

Related Resources