Skip to main content
Using Claude Code, Cursor, or another coding agent? Paste this into your prompt to run cross-browser and real-device tests, debug sessions, and wire up CI on the TestMu AI cloud:

​
Log Locations

Before diagnosing, know where to look: The run_end event in Agent Mode provides session_dir and run_dir directly.

​
Chrome Issues

​
”Chrome failed to launch”

Cause: Chrome is not installed, all CDP ports in the 9222–9230 range are in use, or a profile lock from another running Chrome. Kane CLI manages a Chrome process and connects to it over the Chrome DevTools Protocol (CDP). On macOS it looks under /Applications/Google Chrome.app; on Linux it looks for google-chrome, google-chrome-stable, chromium, and similar binaries; on Windows it looks under Program Files\Google\Chrome\Application\chrome.exe and AppData\Local. Fix:
  1. Install Google Chrome if not present
  2. Check for processes on CDP ports:
  3. Quit any extra Chrome processes hoarding the 9222–9230 port range
  4. Pick a different Chrome user-data directory, or quit the Chrome instance using it. See Chrome Management
  5. If you only need to connect to an already-running Chrome:

​
“CDP endpoint not reachable”

Cause: Using --cdp-endpoint but Chrome is not running on that port. Fix: Remove --cdp-endpoint and let Kane CLI manage Chrome automatically. Or start Chrome with remote debugging before running:

​
Chrome opens then closes immediately

Cause: Another Kane CLI instance is already running and holds the Chrome profile lock. Fix: Check for running kane-cli processes:
Kill any existing processes, then retry.

​
Authentication Issues

​
”Authentication failed” (exit code 2)

Cause: Expired tokens or incorrect credentials. Fix for interactive use:
  1. Re-run the login flow:
  2. Confirm which profile, environment, and token state are active:
    If the token is missing or expired and refresh did not succeed, log in again.
Fix for CI / non-interactive use: Verify both values against the credentials shown in your dashboard, then pass them on the command line:
If they still do not work, regenerate the access key in the dashboard and retry.

​
”Not configured” on first run

Cause: No profile exists yet. Fix: Run the login flow:
Get credentials from the dashboard > Credentials.

​
Basic auth not working

Cause: Wrong username or access key. Fix: Verify your credentials on the dashboard. Username and access key are case-sensitive. Make sure you’re using the access key (not the password).

​
”Login failed — fetch failed” / SSL certificate errors

If kane-cli login exits immediately with Login failed — fetch failed, or a NODE_DEBUG=undici trace shows an OpenSSL error code like UNABLE_TO_GET_ISSUER_CERT_LOCALLY, kane-cli could not validate the TLS certificate of an auth or upload endpoint. Browsers and curl on the same machine will typically still work — this is specific to Node’s default trust store. The cause is that Node ships with its own bundled Mozilla CA list and does not read the operating-system keychain by default. If corporate endpoint security software (EDR), a TLS-inspecting proxy (Zscaler, Netskope, GlobalProtect), or any similar tool signs traffic with a root certificate that lives only in the OS keychain, Node has no way to validate it. Browsers and curl succeed because they trust the keychain natively; Node does not. Fixes, in order of preference:
  1. Tell Node to trust the system keychain. Built-in env var, available on Node 22.19+ / 24.6+:
    See the Node docs. On macOS this reads the default and system keychains using the same trust policy your browser uses, so whatever root makes curl and your browser work will work for kane-cli too.
  2. Point Node at a specific CA bundle. If you are in a corporate setup and your IT or security team can provide the corporate CA file directly, use the standard Node env var:
    This is also the fallback for Node versions older than 22.19, where NODE_USE_SYSTEM_CA is unavailable.
  3. Persist the setting by adding the export line to your shell profile (~/.zshrc, ~/.bashrc, or equivalent) so every new terminal session inherits it. Otherwise the env var only applies to the shell where you ran export.

​
Runner: “[SSL: CERTIFICATE_VERIFY_FAILED]” behind a TLS-inspecting proxy

If kane-cli login succeeds but a run fails mid-execution with an error like:
the failure is in the bundled v16-runner, not in Node. The runner is a standalone Python binary (built with Nuitka) and ships with certifi’s cacert.pem baked in. It does not consult the Windows / macOS / Linux system trust store, and the Node fixes above (NODE_USE_SYSTEM_CA, NODE_EXTRA_CA_CERTS) do not affect it. On a corporate network with a TLS-inspecting proxy (Netskope, Zscaler, GlobalProtect, etc.), the proxy decrypts and re-encrypts HTTPS using its own self-signed root CA. That root is in your OS keychain but not in certifi’s bundle, so the runner’s TLS handshake fails. On a home network there is no MITM, so the chain validates against certifi and the same command works. Fix — give the runner a CA bundle that includes the corporate root:
  1. Get the corporate root CA from IT. On Windows you can export it yourself: open certmgr.msc → Trusted Root Certification Authorities → Certificates, find the proxy’s CA (often named after Netskope / Zscaler / your company), right-click → All Tasks → Export, choose Base-64 encoded X.509 (.cer).
  2. Concatenate it with certifi’s cacert.pem into a single PEM file. On Windows, for example, save the combined file as C:\certs\corp-bundle.pem.
  3. Point the runner at the combined bundle with SSL_CERT_FILE. Windows (persists across new terminals):
    Restart the terminal after setx — the variable is only picked up by new shells. macOS / Linux:
    Add the export line to ~/.zshrc / ~/.bashrc to persist it.
If your environment also breaks kane-cli login, apply the Node-side fix in the previous section as well — the two env vars cover two different processes and you may need both.

​
Run Issues

​
”Run timed out” or “max steps exceeded”

Cause: Objective is too complex, page is slow to load, or --max-steps is too low. Fix:
  • Increase --timeout: --timeout 300
  • Increase --max-steps: --max-steps 60
  • Break the work into smaller objectives. Run several sequential kane-cli run invocations, each focused on one logical sub-task. The session keeps the same browser between runs, so state carries over.
  • Tighten the objective. Vague objectives often cause the agent to wander; describe the target outcome and any required values up front.

​
Agent repeats the same action

Cause: The agent is stuck in a loop: the page didn’t change after the action. Fix: Rephrase the objective to be more explicit. Add an assertion after the action to confirm state changed:

​
“Variables not resolving”: {{key}} appears literally

Cause: Variable file not loaded, wrong JSON format, or wrong variable key name. Fix:
  1. JSON syntax. Variable files are JSON. A missing comma or unquoted key will cause the file to be skipped silently.
  2. File location. Confirm your file is in the right place — see loading order.
  3. Inline test. Bypass file loading by passing the variable on the command line:
    If the inline form works, the issue is with file loading, not the variable itself.

​
Assertions fail even though the page looks correct

Cause: The assertion phrasing doesn’t match what’s on the page, or there’s a timing issue. Fix:
  1. Check the screenshot at {run_dir}/run-test/screenshots/step_NNN.png: see exactly what the agent saw
  2. Refine the assertion: use assert the page contains (substring) instead of exact text
  3. Add a wait: "wait for the confirmation message to appear, then assert..."

​
CLI exits with code 2 and no output

If kane-cli run ends with exit status 2 and the run produces no stdout or stderr after the early startup lines, one of two things is usually happening:
  1. Authentication or setup is missing. This is the common case on a fresh machine. Run kane-cli whoami; if it reports “not configured”, re-run kane-cli login (or pass --username / --access-key in non-interactive environments). See also “Authentication failed” above.
  2. kane-cli was installed via an unsupported package manager — most commonly pnpm. pnpm stores packages under a nested node_modules/.pnpm/ directory, and the resolver for the bundled v16-runner binary does not yet search that layout, so the CLI aborts before it can print a useful error. This limitation is tracked in issue #24; switch to one of the supported install paths listed in Install with pnpm or yarn as a workaround.
To surface the underlying error instead of a silent exit, re-run the same command with KANE_DEV_MODE=1:
In dev mode, setup and resolver failures print an explanatory line before the process exits. Use that message to decide which of the two cases above applies; do not ship KANE_DEV_MODE=1 in production scripts.

​
Upload Issues

​
”Upload failed” or “Test Manager error”

Cause: Kane CLI uploads run artifacts to Test Manager at the end of the session. If the upload fails: Fix:
  1. Authentication. Re-check kane-cli whoami and re-login if needed. Test Manager upload requires a valid token (or basic auth) for the configured environment.
  2. Network connectivity. The upload talks to the control plane and a cloud storage endpoint. Verify outbound HTTPS is not blocked by a proxy or firewall.
  3. Project is set. The pipeline will not commit a test case without a project. Confirm one is configured:
    If project_id is empty, set it with kane-cli config project or pick one in the TUI.

​
Agent Mode Issues

​
No NDJSON output / only seeing TUI

Cause: Missing --agent flag. Fix: Add --agent to your command:

​
NDJSON parsing fails: jq errors or unexpected output

Cause: Stderr is mixing with stdout, or you’re trying to parse mid-stream events. Fix: Redirect stderr and use tail -1 to get only the run_end event:

​
ask_user event fires and blocks the run

Cause: The objective requires human input in an agent context. Fix: Rewrite the objective to avoid prompts. For example, instead of “navigate through the sign-up flow”, be explicit:

​
Installation Issues

​
kane-cli: command not found after install

Cause: npm global bin directory is not in your PATH. Fix:

​
Installation fails

Cause: Node.js version is below 18. Fix: Check your version and upgrade:

​
Install fails with “sharp: Please add node-addon-api”

Symptom: npm install -g @testmuai/kane-cli fails with sharp: Please add node-addon-api to your dependencies (any Node version, any platform).
Kane CLI 0.3.4+ treats sharp as an optional dependency, so the install still succeeds even if sharp fails. Screenshots simply upload as PNG instead of WebP (about 30% larger, no functional impact). On an older version, upgrade first with npm install -g @testmuai/kane-cli@latest.
Cause: sharp powers optional PNG to WebP screenshot compression. When it cannot load its prebuilt binary it tries to build from source, which fails. The most common trigger on macOS is a system-wide libvips (often pulled in by brew install appium, imagemagick, or gdal). Fix (most common, macOS):
Two other triggers: npm configured to skip optional dependencies (npm config get omit should not contain optional, so clear it with npm config delete omit and reinstall), and a proxy or private registry that does not forward the @img scope (add an @img:registry=https://registry.npmjs.org/ pass-through). If you are fine with PNG screenshots, no action is needed.

​
Mobile Issues

Mobile testing is supported on macOS Apple Silicon (arm64) only. Start every mobile problem with doctor, which prints one line per required check, each with a fix:
The common setup failures for each platform, and their fixes, are listed on the mobile testing page:

​
”Update available” Notice

Kane CLI checks the public npm registry for a newer release once every 24 hours. The result is cached locally so the check itself is non-blocking and silent on failure. When a newer version exists, Kane CLI surfaces an “update available” notification with the current and latest versions and a severity label (major, minor, or patch). The notice is informational — your current version still works. To upgrade, follow the steps in Updates.

​
Debugging a failed run with its evidence pack

Every run seals an evidence pack with everything needed to diagnose a failure in one place. The short version:
  1. Open the pack — accept the post-run “View evidence in browser?” offer, or run kane-cli evidence serve <pack> and open the printed viewer URL.
  2. Go to the failed step and read its failure record — the error and the page state at the moment of failure.
  3. Check the step’s console and network logs — a 4xx/5xx response or a JS error there usually explains it.
  4. Compare the annotated screenshot (what the agent acted on) against what you expected.
The full walkthrough is in Evidence packs → Debugging a failed run from its pack, and the pack’s file layout is in Inside the pack. The pack is the only place run logs live — a .evidence file is a plain zip, so even without the viewer you can unzip it and read the logs directly. If a pack won’t open in the viewer, run kane-cli evidence validate <pack> — a truncated or unsealed pack reports invalid; the session directory’s tui.log still has the session narrative. One more debugging aid for batch runs: testrun members normally run silently — set KANE_TESTRUN_MEMBER_DEBUG=1 to route their per-member output to stderr (prefixed [member]).

​
testrun says “plan invalid” or skips members

kane-cli testrun run refuses to start unless every selected test passes preflight; the offenders are listed with a reason each: Use kane-cli testrun run --dry-run … to see the full plan and every offender without executing anything. See Batch runs with testrun.

​
Filing a Bug Report

If you encounter behavior that looks like an agent bug (not auth, timeout, or a vague objective), file an issue: github.com/LambdaTest/kane-cli/issues Include the following: Do NOT file bug reports for: auth issues, low timeouts, vague objectives, or site-side errors (CAPTCHAs, 500 errors).