> ## Documentation Index
> Fetch the complete documentation index at: https://www.testmuai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common Kane CLI issues: Chrome launch failures, authentication errors, run timeouts, variables not resolving, upload failures, and Agent Mode output problems.

export const BrandName = ({type = 'default'}) => {
  const getBrandName = () => 'TestMu AI';
  const getBrandNameLowercase = () => 'testmu ai';
  if (type === 'lowercase') {
    return getBrandNameLowercase();
  }
  return getBrandName();
};

***

<Note>
  **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:

  ```
  Read https://www.testmuai.com/support/docs/SKILL.md to set up TestMu AI (formerly LambdaTest) cloud testing.
  ```
</Note>

## 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:
   ```bash theme={null}
   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](/docs/docs/kane-cli-configuration/#chrome-management)
5. If you only need to connect to an already-running Chrome:
   ```bash theme={null}
   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:

```bash theme={null}
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:

```bash theme={null}
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:
   ```bash theme={null}
   kane-cli login
   ```
2. Confirm which profile, environment, and token state are active:
   ```bash theme={null}
   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 <BrandName /> dashboard, then pass them on the command line:

```bash theme={null}
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:

```bash theme={null}
kane-cli login --username "YOUR_LT_USERNAME" --access-key "YOUR_LT_ACCESS_KEY"
```

Get credentials from the <BrandName /> [dashboard](https://accounts.lambdatest.com/dashboard) > **Credentials**.

### Basic auth not working

**Cause:** Wrong username or access key.

**Fix:** Verify your credentials on the <BrandName /> 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](/docs/docs/kane-cli-variables-and-context/#loading-order).
3. **Inline test.** Bypass file loading by passing the variable on the command line:
   ```bash theme={null}
   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 <BrandName /> 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 <BrandName /> 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:
   ```bash theme={null}
   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:

```bash theme={null}
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:

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
node --version   # Must be 18 or higher
```

### 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).

<Note>
  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`.
</Note>

**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):**

```bash theme={null}
# Diagnose: a printed version means libvips is the cause
pkg-config --modversion vips-cpp

# Bypass libvips detection. Uninstall first, since npm considers
# kane-cli already installed and will not re-resolve sharp otherwise.
npm uninstall -g @testmuai/kane-cli
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g @testmuai/kane-cli

# Make it permanent
echo 'export SHARP_IGNORE_GLOBAL_LIBVIPS=1' >> ~/.zshrc && source ~/.zshrc
```

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:

```bash theme={null}
kane-cli doctor              # required checks, each with a fix if it fails
kane-cli doctor --install    # install the test tooling Kane CLI manages
kane-cli doctor --targets    # list the emulators and simulators available
```

The common setup failures for each platform, and their fixes, are listed on the setup pages:

* [iOS Simulator setup](/docs/docs/kane-cli-mobile-simulator/#common-failures)
* [Android Emulator setup](/docs/docs/kane-cli-mobile-emulator/#common-failures)

***

## "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](/docs/docs/kane-cli-installation/#update).

***

## 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](https://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).