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

# Troubleshooting Octoparse CLI

> Fix common Octoparse CLI errors including auth failures, Chrome issues, Linux arm64 limits, and export problems.

Use this page when a command fails and you are not sure why. Start with `octoparse doctor --json` to get a structured view of your environment.

## Diagnose your environment

```bash theme={null}
octoparse doctor --json
octoparse browser doctor --json
```

Look for any check with `"ok": false` and resolve the flagged dependency before retrying.

## Authentication errors

**`AUTH_REQUIRED` or `AUTH_INVALID`**

The CLI could not find valid credentials. Run:

```bash theme={null}
octoparse auth login
octoparse auth status --json
```

If you are in CI, check that `OCTO_ENGINE_API_KEY` or `OCTO_ENGINE_ACCESS_TOKEN` is set and not expired.

**API key not saving**

The CLI verifies keys before saving. If your key is rejected, confirm it is active in the [Octoparse console](https://www.octoparse.com/console/account-center/api-keys). If using `--stdin`, confirm the key is not padded with extra whitespace or newlines.

**OAuth session expired**

Re-run `octoparse auth login --oauth` to refresh tokens.

## Chrome and browser errors

**Chrome fails to download**

The CLI downloads Chrome for Testing from a CDN automatically. If the download fails:

* Check your network, proxy, or VPN settings.
* Use a locally installed Chrome: `octoparse doctor --chrome-path /path/to/chrome`
* On Linux servers, confirm the CDN is reachable and retry.

**`LINUX_ARM64_UNSUPPORTED`**

Local extraction (`run`, `detect`) is not supported on Linux arm64. Chrome for Testing has no Linux arm64 package.

Options:

* Use a Linux x64 environment or container.
* Use cloud extraction instead: `octoparse cloud start <taskId>`.

**Chrome fails to launch on Linux servers**

On headless Linux servers without a display, `detect` in non-manual mode automatically uses Xvfb when available. Install it if needed:

```bash theme={null}
apt-get install -y xvfb
```

Manual detect (`--manual`) requires an interactive display. Use a desktop or VNC session for manual workflows on Linux.

## Task and run errors

**`TASK_INVALID` or exit code 3**

The task uses kernel browser or legacy workflow not supported by CLI v1. Rebuild the task in the current Octoparse desktop app, then validate with:

```bash theme={null}
octoparse task validate <taskId>
```

**Local run already running**

Only one local run per task ID can be active at a time. Stop the existing run first:

```bash theme={null}
octoparse local stop <taskId>
octoparse local cleanup
```

**Detached run lost or stale**

Clean up orphaned run state:

```bash theme={null}
octoparse local cleanup
```

Then check history:

```bash theme={null}
octoparse local history <taskId>
```

**Run completes but data seems missing**

Check the export source. Local and cloud data are separate:

```bash theme={null}
octoparse data history <taskId> --source local --json
octoparse data history <taskId> --source cloud --json
```

If you used `--output ./runs` during extraction, pass the same path to history and export:

```bash theme={null}
octoparse data history <taskId> --source local --output ./runs
octoparse data export <taskId> --source local --output ./runs --format xlsx
```

## Export errors

**`UNSUPPORTED_EXPORT_FORMAT`**

Supported formats are `xlsx`, `csv`, `html`, `json`, and `xml`. Check your `--format` value.

**Export file is empty**

Confirm the task collected rows before exporting. Check local run history:

```bash theme={null}
octoparse local history <taskId> --json
```

Look for `savedRows > 0` in the most recent run entry.

## Detect errors

**`DETECT_FAILED` or no candidates found**

The page may have blocked automated access, shown a login gate, or loaded content dynamically. Try:

* `--manual` to handle login or popups yourself.
* `--goal` to give the CLI a clearer extraction target.
* Checking the generated screenshot in the agent context (`context.screenshot.path`).

**`LOGIN_SESSION_REQUIRED`**

Use manual detect with session saving:

```bash theme={null}
octoparse detect <url> --manual --save-session --session-name my-session
```

## Getting help

Run `octoparse --help` or `octoparse <command> --help` for usage details.

Share the output of `octoparse doctor --json` with Octoparse support when reporting environment issues.

<Card title="Contact Octoparse support" href="https://www.octoparse.com/contact">
  Include your CLI version (`octoparse --version`) and `octoparse doctor --json` output.
</Card>