En esta página se ofrecen consejos para solucionar problemas y estrategias de depuración que pueden resultarte útiles si usas plantillas flexibles de Dataflow. Esta información puede ayudarte a detectar un tiempo de espera de la consulta, determinar el motivo y corregir el problema.
Errores de tiempo de espera de sondeo
Es posible que tu trabajo devuelva uno de los siguientes mensajes de error:
Timeout in polling result file: FILE_PATH. Possible causes are:
1. Your launch takes too long time to finish. Please check the logs on stackdriver.
2. Service account SERVICE_ACCOUNT may not have enough permissions to pull
container image IMAGE_PATH or create new objects in FILE_PATH.
3. Transient errors occurred, please try again.
Timeout in polling result file: FILE_PATH.
Service account: SERVICE_ACCOUNT
Image URL: IMAGE_PATH
Troubleshooting guide at https://cloud.google.com/dataflow/docs/guides/common-errors#timeout-polling
Este error puede producirse por los siguientes motivos:
- Se ha anulado la imagen Docker base.
- La cuenta de servicio que rellena SERVICE_ACCOUNT no tiene algunos permisos necesarios.
- Las direcciones IP externas están inhabilitadas y las VMs no pueden conectarse al conjunto de direcciones IP externas que usan las APIs y los servicios de Google.
- El programa que crea el gráfico tarda demasiado en finalizar.
- Se están sobrescribiendo las opciones de flujo de procesamiento.
- Usuarios de Python: hay un problema con el archivo
requirements.txt. - Se ha producido un error transitorio.
Para solucionar este problema, primero comprueba si hay errores transitorios consultando los registros de trabajos y volviendo a intentarlo.
Si el problema persiste, prueba a seguir estos pasos para solucionarlo.
Opcional: Ejecuta plantillas para diagnosticar mejor el problema
Para identificar cuál de los motivos anteriores puede estar causando este error, sigue estas estrategias:
Ejecuta la plantilla WordCount proporcionada por Google. Asegúrate de proporcionar parámetros únicos para tu caso de uso, como la subred de un proyecto de VPC compartida, la IP privada de las VMs de trabajador y la cuenta de servicio de trabajador de Dataflow que quieras usar. Para obtener más información sobre cómo proporcionar estos parámetros, consulta la referencia de gcloud y la referencia de la API.
Si puedes completar este trabajo correctamente, significa que es probable que la red, los permisos de gestión de identidades y accesos y el acceso privado a Google estén configurados correctamente.
Completa la guía de inicio rápido Ejecutar una canalización con el creador de tareas, que ejecuta la tarea como una plantilla flexible. Si tu trabajo falla antes de iniciar la VM de trabajador, accede a la VM de inicio e intenta descargar una imagen de Docker de muestra con un comando similar al siguiente:
docker run --entrypoint /bin/bash -it gcr.io/dataflow-templates/2025-03-11-00_rc02/yaml-templateSi este comando falla, puede que haya un problema de red al descargar imágenes. En ese caso, ponte en contacto con tu equipo de redes interno.
Ejecuta una plantilla Flex proporcionada por Google y comprueba el resultado. Si el trabajo de plantilla proporcionado por Google se completa correctamente, esto indica que el problema probablemente esté relacionado con los archivos de código de tu plantilla personalizada específica. En ese caso, debes seguir solucionando el problema con tu código específico.
Verificar el punto de entrada de Docker
Prueba este paso si estás ejecutando una plantilla desde una imagen Docker personalizada en lugar de usar una de las plantillas proporcionadas.
Comprueba el punto de entrada del contenedor con el siguiente comando:
docker inspect $TEMPLATE_IMAGE
Se espera el siguiente resultado:
Java
/opt/google/dataflow/java_template_launcher
Python
/opt/google/dataflow/python_template_launcher
Si obtienes un resultado diferente, significa que se ha anulado el punto de entrada de tu contenedor Docker. Restablece $TEMPLATE_IMAGE a su valor predeterminado.
Comprobar los permisos de la cuenta de servicio
Comprueba que la cuenta de servicio mencionada en el mensaje tenga los siguientes permisos:
- Debe poder leer y escribir en la ruta de Cloud Storage que se indica en
${file_path}del mensaje. - Debe poder leer la imagen de Docker que rellena
${image_url}en el mensaje.
Configurar Acceso privado de Google
Si las direcciones IP externas están inhabilitadas, debes permitir que las VMs de Compute Engine se conecten al conjunto de direcciones IP externas que usan las APIs y los servicios de Google. Habilita el acceso privado a Google en la subred que usa la interfaz de red de la VM.
Para obtener información detallada sobre la configuración, consulta el artículo Configurar Acceso privado de Google.
De forma predeterminada, cuando una VM de Compute Engine no tiene asignada una dirección IP externa a su interfaz de red, solo puede enviar paquetes a otros destinos de direcciones IP internas.
Comprobar si el programa de inicio no se cierra
El programa que crea la canalización debe finalizar antes de que se pueda iniciar. El error de sondeo podría indicar que ha tardado demasiado en hacerlo.
Estas son algunas de las cosas que puedes hacer para localizar la causa en el código:
- Consulta los registros de trabajos y comprueba si alguna operación tarda mucho en completarse. Por ejemplo, una solicitud de un recurso externo.
- Asegúrate de que ningún subproceso impida que el programa se cierre. Es posible que algunos clientes creen sus propios hilos y, si no se cierran, el programa esperará indefinidamente a que se unan estos hilos.
Las canalizaciones que se inician directamente y no usan una plantilla no tienen estas limitaciones. Por lo tanto, si la canalización ha funcionado directamente, pero no como plantilla, es posible que el uso de una plantilla sea la causa principal. Si encuentras el problema en la plantilla y lo corriges, es posible que se solucione.
Verificar si se suprimen las opciones de canalización obligatorias
Cuando usas plantillas Flex, puedes configurar algunas opciones de la canalización, pero no todas, durante la inicialización de la canalización. Para obtener más información, consulta la sección No se ha podido leer el archivo de trabajo de este documento.
Usuarios de Python: elimina Apache Beam del archivo de requisitos
Si tu Dockerfile incluye un requirements.txt con apache-beam[gcp],
elimínalo del archivo e instálalo por separado. El siguiente comando
muestra cómo completar este paso:
RUN pip install apache-beam[gcp]
RUN pip install -U -r ./requirements.txt
Si incluyes Apache Beam en el archivo de requisitos, los tiempos de lanzamiento pueden ser largos, lo que a menudo provoca un tiempo de espera agotado. Para obtener más información, consulta el seguimiento de errores del equipo de Apache Arrow.
Usuarios de Python: empaquetar previamente las dependencias
Si ejecutas una tarea de Dataflow con una plantilla flexible y Python, es posible que la tarea se ponga en cola durante un periodo, no se ejecute y, a continuación, muestre el siguiente error:
Timeout in polling
El archivo requirements.txt que se usa para instalar las dependencias necesarias provoca el error. Cuando inicias un trabajo de Dataflow, primero se almacenan todas las dependencias para que las VMs de los trabajadores puedan acceder a estos archivos.
Este proceso implica descargar y compilar todas las dependencias directas e indirectas del archivo requirements.txt. Algunas dependencias pueden tardar varios minutos en compilarse. Cabe destacar que PyArrow puede tardar en compilarse. PyArrow es una dependencia indirecta que utilizan Apache Beam y la mayoría de las bibliotecas de cliente de Cloud.
Para optimizar el rendimiento de tu trabajo, usa un archivo Dockerfile o un contenedor personalizado para preempaquetar las dependencias. Para obtener más información, consulta Dependencias de paquetes en "Configurar plantillas flexibles".
Errores de inicio de tareas
En la siguiente sección se describen los errores habituales que provocan fallos en el inicio de los trabajos y los pasos para resolverlos o solucionarlos.
Problemas de inicio anticipado
Si el proceso de lanzamiento de la plantilla falla en una fase inicial, es posible que los registros de FlexTemplate normales no estén disponibles. Para investigar los problemas de inicio, habilita el registro del puerto serie de la VM del lanzador de plantillas.
Para habilitar el registro de plantillas Java, asigna el valor true a la opción enableLauncherVmSerialPortLogging. Para habilitar el registro de plantillas de Python y Go, asigna el valor true a la opción enable_launcher_vm_serial_port_logging. En la consola de Google Cloud , el parámetro se muestra en Parámetros opcionales como Habilitar registro del puerto serie de la VM de Launcher.
Puedes ver los registros de salida del puerto serie de la VM de inicio de plantillas en Cloud Logging. Para encontrar los registros de una VM de un launcher concreto, usa la consulta
resource.type="gce_instance" "launcher-number" donde number empieza
con la fecha actual en el formato YYYMMDD.
Es posible que la política de tu organización te impida habilitar el registro de salidas del puerto serie.
No se ha podido leer el archivo de trabajo
Cuando intentas ejecutar un trabajo a partir de una plantilla flexible, es posible que el trabajo falle y se muestre el siguiente error:
Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object...
Este error se produce cuando se sobrescriben las opciones de inicialización de la canalización necesarias. Cuando usas plantillas Flex, puedes configurar algunas opciones del flujo de procesamiento, pero no todas, durante la inicialización del flujo. Si se sobrescriben los argumentos de línea de comandos que requiere la plantilla flex, es posible que el trabajo ignore, sobrescriba o descarte las opciones de la canalización que haya pasado el lanzador de plantillas. Es posible que la tarea no se inicie o que se inicie una tarea que no use la plantilla Flex.
Para evitar este problema, durante la inicialización de la canalización, no cambies las siguientes opciones de canalización en el código de usuario ni en el archivo metadata.json:
Java
runnerprojectjobNametemplateLocationregion
Python
runnerprojectjob_nametemplate_locationregion
Go
runnerprojectjob_nametemplate_locationregion
No se ha podido leer el archivo de resultados
Cuando intentas ejecutar un trabajo a partir de una plantilla flexible, es posible que el trabajo falle y se muestre el siguiente error:
Failed to read the result file : gs://BUCKET_NAME...
Este error se produce cuando la cuenta de servicio predeterminada de Compute Engine no tiene todos los permisos que necesita para ejecutar una plantilla flexible. Para ver la lista de permisos necesarios, consulta Permisos para ejecutar una plantilla flexible.
Permiso denegado en el recurso
Cuando intentas ejecutar un trabajo a partir de una plantilla flexible, es posible que el trabajo falle y se muestre el siguiente error:
Permission "MISSING_PERMISSION" denied on resource "projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME" (or it may not exist).
Este error se produce cuando la cuenta de servicio utilizada no tiene permisos para acceder a los recursos necesarios para ejecutar una plantilla flex.
Para evitar este problema, comprueba que la cuenta de servicio tenga los permisos necesarios. Ajusta los permisos de la cuenta de servicio según sea necesario.
Se ha proporcionado una marca, pero no se ha definido
Cuando intentas ejecutar una plantilla flexible de Go con la opción worker_machine_type, el flujo de procesamiento falla y aparece el siguiente error:
flag provided but not defined: -machine_type
Este error se debe a un problema conocido en las versiones 2.47.0 y anteriores del SDK de Apache Beam Go. Para solucionar este problema, actualiza a la versión 2.48.0 o a una posterior de Apache Beam Go.
No se puede obtener el archivo JAR del servidor de trabajos remoto
Si intentas ejecutar un trabajo desde una plantilla flexible cuando no tienes conexión a Internet, es posible que el trabajo falle y se muestre el siguiente error:
Unable to fetch remote job server jar at
https://repo.maven.apache.org/maven2/org/apache/beam/beam-sdks-java-io-expansion-service/VERSION/beam-sdks-java-io-expansion-service-VERSION.jar:
\u003curlopen error [Errno 101] Network is unreachable\u003e
Este error se produce porque la VM no puede descargar el paquete Java de Apache Beam de Internet. Este paquete es obligatorio cuando ejecutas un trabajo multilingüe con una plantilla flex.
Para solucionar este problema, haz uno de los siguientes cambios:
Conéctate a Internet. Cuando tengas conexión a Internet, tu trabajo podrá acceder al archivo necesario.
Incluye el paquete Java de Apache Beam en tu directorio local para que tu trabajo pueda acceder a él de forma local. Coloca el archivo en el siguiente directorio:
/root/.apache_beam/cache/jars/. Por ejemplo,/root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar.
No se puede obtener el sistema de archivos de la ruta especificada
Cuando intentas ejecutar un trabajo a partir de una plantilla flexible, es posible que el trabajo falle y se muestre el siguiente error:
ValueError: Unable to get filesystem from specified path, please use
the correct path or ensure the required dependency is installed, e.g., pip
install apache-beam[gcp]. Path specified: PATH
Este error se produce cuando el trabajo usa una imagen de contenedor de plantilla Flex y la imagen de contenedor no contiene una instalación de Java.
Para solucionar este problema, añade la siguiente línea a tu archivo Dockerfile:
sh
RUN apt-get update && apt-get install -y openjdk-17-jdk
Este comando instala Java en tu entorno de contenedor.
Retraso del iniciador de plantillas Flex
Cuando envías una tarea de plantilla flexible, la solicitud de tarea se añade a una cola de Spanner. El launcher de plantillas toma la tarea de la cola de Spanner y, a continuación, ejecuta la plantilla. Cuando Spanner tiene un retraso de mensajes, puede haber un retraso significativo entre el momento en que envías el trabajo y el momento en que se inicia.
Para solucionar este problema, inicia tu plantilla Flex desde otra región.
Los parámetros de plantilla no son válidos
Cuando intentas usar la CLI de gcloud para ejecutar un trabajo que usa una plantilla proporcionada por Google, se produce el siguiente error:
ERROR: (gcloud.beta.dataflow.flex-template.run) INVALID_ARGUMENT: The template
parameters are invalid. Details: defaultSdkHarnessLogLevel: Unrecognized
parameter defaultWorkerLogLevel: Unrecognized parameter
Este error se produce porque algunas plantillas proporcionadas por Google no admiten las opciones defaultSdkHarnessLog y defaultWorkerLog.
Como solución alternativa, copia el archivo de especificación de la plantilla en un segmento de Cloud Storage. Añade los siguientes parámetros adicionales al archivo.
"metadata": {
...
"parameters": [
...,
{
"name": "defaultSdkHarnessLogLevel",
"isOptional": true,
"paramType": "TEXT"
},
{
"name": "defaultWorkerLogLevel",
"isOptional": true,
"paramType": "TEXT"
}
]
}
Después de hacer este cambio en el archivo de plantilla, usa el siguiente comando para ejecutarla.
--template-file-gcs-location=gs://BUCKET_NAME/FILENAME
Sustituye los siguientes valores:
BUCKET_NAME: el nombre de tu segmento de Cloud StorageFILENAME: el nombre del archivo de especificación de la plantilla
Los registros del lanzador de plantillas Flex muestran una gravedad incorrecta
Cuando falla el inicio de una plantilla Flex personalizada, aparece el siguiente mensaje en los archivos de registro con la gravedad ERROR:
ERROR: Error occurred in the launcher container: Template launch failed. See console logs.
La causa principal del fallo de lanzamiento suele aparecer en los registros antes de este mensaje con la gravedad INFO. Aunque este nivel de registro puede ser incorrecto, es el esperado, ya que el lanzador de plantillas Flex no puede extraer detalles de gravedad de los mensajes de registro generados por la aplicación Apache Beam.
Si quieres ver la gravedad correcta de cada mensaje del registro del launcher, configura tu plantilla para que genere registros en formato JSON en lugar de texto sin formato. Esta configuración permite que el lanzador de plantillas extraiga la gravedad correcta del mensaje de registro. Usa la siguiente estructura de mensaje:
{
"message": "The original log message",
"severity": "DEBUG/INFO/WARN/ERROR"
}
En Java, puedes usar el registrador Logback con una implementación personalizada de appender JSON. Para obtener más información, consulta la configuración de ejemplo de Logback y el código de ejemplo de Appender JSON en GitHub.
Este problema solo afecta a los registros generados por el lanzador de plantillas flexibles cuando se inicia la canalización. Cuando el lanzamiento se realiza correctamente y la canalización se está ejecutando, los registros generados por los trabajadores de Dataflow tienen la gravedad adecuada.
Las plantillas proporcionadas por Google muestran la gravedad correcta durante el inicio del trabajo, ya que usan este enfoque de registro JSON.