Skip to main content

Errores comunes

La prueba de privilegios falló o las operaciones fallan por problemas de permisos

Mensaje de error:
Causa: El usuario de Fivetran no tiene los privilegios necesarios. El conector requiere los privilegios ALTER, CREATE DATABASE, CREATE TABLE, INSERT y SELECT sobre *.* (todas las bases de datos y tablas).
La comprobación de privilegios consulta system.grants y solo tiene en cuenta los privilegios otorgados directamente al usuario. No detecta los privilegios asignados mediante un rol de ClickHouse. Consulta la sección privilegios basados en roles para obtener más información.
Solución: Otorga directamente al usuario de Fivetran los privilegios necesarios:

Error al esperar a que finalicen todas las mutaciones

Mensaje de error:
Causa: Se envió una mutación ALTER TABLE ... UPDATE o ALTER TABLE ... DELETE, pero el conector agotó el tiempo de espera mientras esperaba a que se completara en todas las réplicas. La parte de la “causa inicial” del error suele contener el error original de ClickHouse (normalmente el código 341, “Unfinished”). Esto puede ocurrir cuando:
  • El clúster de ClickHouse Cloud está sometido a una carga elevada.
  • Uno o más nodos dejaron de estar disponibles durante la ejecución de la mutación.
Soluciones:
  1. Comprobar el progreso de la mutación: Ejecute la siguiente consulta para comprobar si hay mutaciones pendientes:
  2. Comprobar el estado del clúster: Asegúrese de que todos los nodos estén en buen estado.
  3. Esperar y reintentar: Las mutaciones terminan completándose una vez que el clúster vuelve a estar en buen estado. Fivetran reintentará la sincronización automáticamente.

Error de incompatibilidad de columnas

Mensaje de error: Pueden producirse distintos errores si la incompatibilidad entre columnas se debe a un cambio de esquema en el origen. Por ejemplo:
O:
Causa: Las columnas de la tabla de destino de ClickHouse no coinciden con las columnas de los datos que se están sincronizando. Esto puede ocurrir cuando:
  • Se añadieron o eliminaron columnas manualmente en la tabla de ClickHouse.
  • Un cambio de esquema en el origen no se propagó correctamente.
Soluciones:
  1. Recuerde no modificar manualmente las tablas gestionadas por Fivetran. Consulte buenas prácticas.
  2. Restaure la columna: Si sabe qué tipo debería tener la columna, restáurela al tipo esperado tomando como referencia la correspondencia de transformación de tipos.
  3. Vuelva a sincronizar la tabla: En el panel de Fivetran, active una resincronización histórica para la tabla afectada.
  4. Eliminar y volver a crear: Como último recurso, elimine la tabla de destino y deje que Fivetran la vuelva a crear durante la siguiente sincronización.

El AST es demasiado grande (código 168)

Mensaje de error:
o
Causa: Los lotes grandes de UPDATE o DELETE generan sentencias SQL con árboles de sintaxis abstracta muy complejos. Esto es habitual con tablas anchas o cuando el modo de historial está habilitado. Solución: Reduzca mutation_batch_size y hard_delete_batch_size en el archivo de configuración avanzada. Ambos tienen como valor predeterminado 1500 y aceptan valores entre 200 y 1500.

Límite de memoria superado / OOM (código 241)

Mensaje de error:
Causa: La operación INSERT requiere más memoria de la disponible. Suele ocurrir durante sincronizaciones iniciales de gran volumen, con tablas con muchas columnas o con operaciones por lotes concurrentes. Soluciones:
  1. Reducir write_batch_size: Intenta bajarlo a 50,000 para tablas grandes.
  2. Reducir la carga de la base de datos: Comprueba la carga del servicio de ClickHouse Cloud para ver si está sobrecargado.
  3. Ampliar el servicio de ClickHouse Cloud para disponer de más memoria.

EOF inesperado / Error de conexión

Mensaje de error:
O FAILURE_WITH_TASK sin stack trace en los logs de Fivetran. Causa:
  • La lista de acceso IP no está configurada para permitir el tráfico de Fivetran.
  • Problemas transitorios de red entre Fivetran y ClickHouse Cloud.
  • Datos de origen corruptos o no válidos que provocan que el conector de destino falle.
Soluciones:
  1. Comprobar la lista de acceso IP: En ClickHouse Cloud, ve a Settings > Security y añade las direcciones IP de Fivetran o permite el acceso desde cualquier origen.
  2. Reintentar: Las versiones recientes del conector reintentan automáticamente los errores EOF. Los errores esporádicos (1–2 al día) probablemente sean transitorios.
  3. Si el problema persiste: Abre un ticket de soporte con ClickHouse e indica la ventana de tiempo del error. Pide también al soporte de Fivetran que investigue la calidad de los datos de origen.

No se puede mapear el tipo UInt64

Mensaje de error:
Causa: El conector asigna LONG a Int64, nunca a UInt64. Este error se produce cuando el tipo de una columna se modifica manualmente en una tabla gestionada por Fivetran. Soluciones:
  1. No modifique manualmente los tipos de las columnas en las tablas gestionadas por Fivetran.
  2. Para solucionarlo: vuelva a cambiar la columna al tipo esperado (por ejemplo, Int64) o elimine la tabla y vuelva a sincronizarla.
  3. Para tipos personalizados: Cree una vista materializada sobre la tabla gestionada por Fivetran.

La tabla no tiene claves primarias

Mensaje de error:
Causa: Toda tabla de ClickHouse requiere un ORDER BY. Cuando el origen no tiene una clave primaria, Fivetran agrega _fivetran_id automáticamente. Este error se produce en casos excepcionales en los que el origen define una PK, pero los datos no la contienen. Soluciones:
  1. Contacta con el soporte de Fivetran para investigar la canalización de origen.
  2. Comprueba el esquema de origen: Asegúrate de que las columnas de la clave primaria estén presentes en los datos.

Fallo en los privilegios basados en roles

Mensaje de error:
Causa: El conector verifica los privilegios con:
Esto solo devuelve los privilegios concedidos directamente. Los privilegios asignados mediante un rol de ClickHouse tienen user_name = NULL y role_name = 'my_role', por lo que esta comprobación no los detecta. Solución: Concede los privilegios directamente al usuario de Fivetran:

Buenas prácticas

Servicio de ClickHouse dedicado para Fivetran

En caso de una alta carga de ingestión, considere usar la separación de cómputo y cómputo de ClickHouse Cloud para crear un servicio dedicado a las cargas de escritura de Fivetran. Esto aísla la ingestión de las consultas analíticas y evita la contención de recursos. Por ejemplo, puede usarse la siguiente arquitectura:
  • Servicio A (escritura): destino de Fivetran + otras herramientas de ingestión (ClickPipes, conectores de Kafka)
  • Servicio B (lectura): herramientas de BI, dashboards, consultas ad hoc

Optimización de las consultas de lectura

ClickHouse usa SharedReplacingMergeTree para las tablas de destino de Fivetran, que es la versión del motor de tabla ReplacingMergeTree en ClickHouse Cloud. Las filas duplicadas con la misma clave primaria son normales: la deduplicación se produce de forma asíncrona durante las fusiones en segundo plano. En el momento de la lectura, debes tener cuidado para evitar devolver filas duplicadas, ya que es posible que algunas filas aún no se hayan deduplicado. Usar la palabra clave FINAL es la forma más sencilla de evitar filas duplicadas, ya que fuerza la fusión, en el momento de la lectura, de cualquier fila que todavía no se haya deduplicado:
Hay formas de optimizar esta operación FINAL; por ejemplo, filtrando por las columnas clave mediante una condición WHERE. Para obtener más información, consulta la sección rendimiento de FINAL de la guía de ReplacingMergeTree. Si esas optimizaciones no son suficientes, tienes otras opciones para evitar usar FINAL sin dejar de gestionar correctamente los duplicados:

Optimización de la clave primaria y ORDER BY

Fivetran replica la clave primaria de la tabla de origen como la cláusula ORDER BY de ClickHouse. Cuando la tabla de origen no tiene PK, _fivetran_id (un UUID) pasa a ser la clave de ordenación, lo que puede provocar un rendimiento deficiente en las consultas, ya que ClickHouse construye su índice primario disperso a partir de las columnas de ORDER BY. Recomendaciones en este caso, si ninguna otra optimización es suficiente:
  1. Trate las tablas de Fivetran como tablas de staging sin procesar. No las consulte directamente para análisis.
  2. Si las consultas siguen sin ofrecer un rendimiento suficiente, use una vista materializada actualizable para crear una copia de la tabla con un ORDER BY optimizado para sus patrones de consulta. A diferencia de las vistas materializadas incrementales, las vistas materializadas actualizables vuelven a ejecutar la consulta completa según una programación, lo que gestiona correctamente las operaciones UPDATE y DELETE que Fivetran ejecuta durante las sincronizaciones:
Evite las vistas materializadas incrementales (no actualizables) en tablas gestionadas por Fivetran. Como Fivetran ejecuta operaciones UPDATE y DELETE para mantener los datos sincronizados, las vistas materializadas incrementales no reflejarán estos cambios y contendrán datos obsoletos o incorrectos.

No modifiques manualmente las tablas gestionadas por Fivetran

Evita hacer cambios manuales de DDL (p. ej., ALTER TABLE ... MODIFY COLUMN) en las tablas gestionadas por Fivetran. El conector espera el esquema que creó. Los cambios manuales pueden provocar errores de correspondencia de tipos y fallos por incompatibilidades de esquema. Usa vistas materializadas para las transformaciones personalizadas.

Operaciones de depuración

Al diagnosticar fallos:
  • Consulte el system.query_log de ClickHouse para detectar problemas del lado del servidor.
  • Solicite ayuda a Fivetran si los problemas son del lado del cliente.
Para errores del conector, cree una incidencia en GitHub o póngase en contacto con soporte de ClickHouse.

Depuración de sincronizaciones de Fivetran

Utilice las siguientes consultas para diagnosticar fallos de sincronización en ClickHouse.

Revisa los errores recientes de ClickHouse relacionados con Fivetran

Consultar la actividad reciente del usuario de Fivetran

Última modificación el 3 de julio de 2026