Skip to main content

​
Log Locations

Before diagnosing, know where to look:
LogPath
Run text log{run_dir}/run.log
Step detail (JSON){run_dir}/run-test/step_NNN.json
Step screenshot{run_dir}/run-test/screenshots/step_NNN.png
Run summary{run_dir}/run-test/run_summary.json
Session log{session_dir}/tui.log
All sessions~/.testmuai/kaneai/sessions/
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: 
    lsof -i :9222-9230
  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: 
    kane-cli run "..." --cdp-endpoint http://localhost:9222

​
“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: 
google-chrome --remote-debugging-port=9222 &
kane-cli run "..." --cdp-endpoint http://localhost:9222

​
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: 
ps aux | grep kane-cli
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: 
    kane-cli login
  2. Confirm which profile, environment, and token state are active: 
    kane-cli whoami
    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: 
kane-cli run "<objective>" \
  --username "YOUR_LT_USERNAME" \
  --access-key "YOUR_LT_ACCESS_KEY"
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: 
kane-cli login --username "YOUR_LT_USERNAME" --access-key "YOUR_LT_ACCESS_KEY"
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).

​
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: 
"click the Save button, assert the page shows 'Saved successfully'"

​
“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: 
    kane-cli run "log in as {{user}}" \
  --variables '{"user":{"value":"alice"}}'
    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..."

​
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: 
    kane-cli config show
    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: 
kane-cli run "..." --agent --headless

​
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: 
kane-cli run "..." --agent 2>/dev/null | tail -1 | jq .

​
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: 
"click Sign Up, fill email with '{{email}}', fill password with '{{password}}', click Create Account"

​
Installation Issues

​
kane-cli: command not found after install

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

# Add to PATH (adjust path based on above output)
export PATH="$(npm config get prefix)/bin:$PATH"

# Make permanent: add to ~/.zshrc or ~/.bashrc
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc

​
Installation fails

Cause: Node.js version is below 18. Fix: Check your version and upgrade: 
node --version   # Must be 18 or higher

​
“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.

​
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:
FieldHow to Get It
Kane CLI versionkane-cli --version
OSmacOS (ARM/Intel), Linux (x64/ARM64), Windows (x64)
What happenedDescribe the behavior
Reproduction stepsThe exact kane-cli run command and objective
Expected behaviorWhat should have happened
Logsrun_summary.json and step_NNN.json from run_dir
Screenshotscreenshots/step_NNN.png from run_dir
Do NOT file bug reports for: auth issues, low timeouts, vague objectives, or site-side errors (CAPTCHAs, 500 errors).