Skip to main content
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

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: 
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. 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: 
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: 
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: 
octoparse local stop <taskId>
octoparse local cleanup
Detached run lost or stale Clean up orphaned run state: 
octoparse local cleanup
Then check history: 
octoparse local history <taskId>
Run completes but data seems missing Check the export source. Local and cloud data are separate: 
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: 
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: 
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: 
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.

Contact Octoparse support

Include your CLI version (octoparse --version) and octoparse doctor --json output.