Troubleshooting

Log Locations

Before diagnosing, know where to look:

Log	Path
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 TestMu AI dashboard, then pass them on the command line:

kane-cli run "<objective>" \
--username "undefined" \
--access-key "undefined"

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 "undefined" --access-key "undefined"

Get credentials from the TestMu AI dashboard > Credentials.

Basic auth not working

Cause: Wrong username or access key.

Fix: Verify your credentials on the TestMu AI 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 TestMu AI 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 TestMu AI 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:

Field	How to Get It
Kane CLI version	kane-cli --version
OS	macOS (ARM/Intel), Linux (x64/ARM64), Windows (x64)
What happened	Describe the behavior
Reproduction steps	The exact kane-cli run command and objective
Expected behavior	What should have happened
Logs	run_summary.json and step_NNN.json from run_dir
Screenshot	screenshots/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).