Skip to main content
Usa esta página cuando un comando falle y no sepas por qué. Empieza por octoparse doctor --json para obtener una vista estructurada del entorno.

​
Diagnosticar el entorno

Busca cualquier comprobación que contenga "ok": false y resuelve la dependencia indicada antes de volver a intentarlo.

​
Errores de autenticación

AUTH_REQUIRED o AUTH_INVALID La CLI no ha encontrado credenciales válidas. Ejecuta:
En CI, comprueba que OCTO_ENGINE_API_KEY o OCTO_ENGINE_ACCESS_TOKEN esté definido y no haya caducado. La clave de API no se guarda La CLI verifica las claves antes de guardarlas. Si rechaza la tuya, confirma que esté activa en la consola de Octoparse. Si usas --stdin, comprueba que la clave no incluya espacios en blanco ni saltos de línea adicionales. La sesión de OAuth ha caducado Vuelve a ejecutar octoparse auth login --oauth para actualizar los tokens.

​
Errores de Chrome y del navegador

Chrome no se descarga La CLI descarga automáticamente Chrome for Testing desde una CDN. Si falla la descarga:
  • Comprueba la configuración de red, Proxy o VPN.
  • Usa un Chrome instalado localmente: octoparse doctor --chrome-path /path/to/chrome.
  • En servidores Linux, confirma que la CDN sea accesible y vuelve a intentarlo.
LINUX_ARM64_UNSUPPORTED La extracción local (run, detect) no es compatible con Linux arm64. Chrome for Testing no ofrece un paquete para Linux arm64. Opciones:
  • Usa un entorno o contenedor Linux x64.
  • Usa la extracción en la nube: octoparse cloud start <taskId>.
Chrome no se inicia en servidores Linux En servidores Linux sin interfaz gráfica, detect en modo no manual utiliza Xvfb automáticamente cuando está disponible. Instálalo si es necesario:
La detección manual (--manual) requiere una pantalla interactiva. En Linux, usa un escritorio o una sesión VNC para los flujos manuales.

​
Errores de tareas y ejecuciones

TASK_INVALID o código de salida 3 La tarea utiliza un navegador de kernel o un flujo heredado que CLI v1 no admite. Vuelve a crearla en la aplicación de escritorio actual de Octoparse y valídala:
Ya hay una ejecución local en curso Solo puede haber una ejecución local activa por ID de tarea. Detén primero la existente:
Ejecución en segundo plano perdida u obsoleta Limpia el estado de las ejecuciones huérfanas:
Después, comprueba el historial:
La ejecución termina, pero parecen faltar datos Comprueba el origen de la exportación. Los datos locales y los de la nube están separados:
Si usaste --output ./runs durante la extracción, pasa la misma ruta al historial y a la exportación:

​
Errores de exportación

UNSUPPORTED_EXPORT_FORMAT Los formatos compatibles son xlsx, csv, html, json y xml. Comprueba el valor de --format. El archivo exportado está vacío Confirma que la tarea haya recopilado filas antes de exportar. Comprueba el historial de ejecución local:
Busca savedRows > 0 en la entrada de ejecución más reciente.

​
Errores de detección

DETECT_PAGE_BLOCKED La CLI ha identificado el destino como un CAPTCHA, un desafío de seguridad, una página con acceso restringido o una página de error del servicio. Se detiene antes de crear una tarea para evitar que el archivo resultante describa la pantalla de verificación o error.
  • Resuelve el CAPTCHA o la restricción de acceso y vuelve a intentarlo.
  • Usa --manual si puedes completar la interacción necesaria en el navegador.
  • Proporciona una URL accesible directamente si la actual siempre redirige a una página bloqueada.
DETECT_FAILED o no se encontraron candidatos Es posible que la página haya bloqueado el acceso automatizado, mostrado una barrera de inicio de sesión o cargado el contenido de forma dinámica. Prueba lo siguiente:
  • Usa --manual para gestionar personalmente el inicio de sesión o las ventanas emergentes.
  • Usa --goal para indicar a la CLI un objetivo de extracción más claro.
  • Comprueba la captura generada en el contexto del agente (context.screenshot.path).
LOGIN_SESSION_REQUIRED Usa la detección manual y guarda la sesión:

​
Obtener ayuda

Ejecuta octoparse --help u octoparse <command> --help para consultar el uso. Cuando informes de problemas del entorno, comparte con el equipo de soporte de Octoparse el resultado de octoparse doctor --json.

Contactar con el soporte de Octoparse

Incluye la versión de la CLI (octoparse --version) y el resultado de octoparse doctor --json.