Solución de problemas

Referencia de síntomas, causas y soluciones para los fallos que pueden surgir durante este laboratorio, agrupados según dónde aparecen.

Todas las entradas siguientes corresponden a fallos reales: los once documentados en los README de las propias partes del laboratorio y otros cinco detectados al crear y probar este taller. Busca tu síntoma, lee la causa y aplica la solución. Si ninguno coincide, las secciones ## Common failures del itinerario del instructor explican con más detalle la perspectiva del facilitador para cada módulo; después, consulta a tu arquitecto de soluciones.

Cadena de herramientas y configuración

`dbt` falla con un error de importación de `mashumaro` o no se instala

Síntoma: falla la instalación de dbt-snowflake o dbt-clickhouse, o dbt genera un error de importación que menciona mashumaro y que, a primera vista, no guarda relación con tu versión de Python.
Causa: tanto dbt-snowflake como dbt-clickhouse requieren Python 3.11, 3.12 o 3.13. Python 3.14 o posterior rompe su dependencia compartida de mashumaro, y el fallo suele aparecer en un módulo no relacionado cuando el error ya se ha producido.
Solución: instala 3.13 junto con el Python del sistema (por ejemplo, brew install python@3.13) y vuelve a crear el entorno virtual indicando explícitamente ese intérprete: python3.13 -m venv .venv.

El entorno de origen Snowflake

`terraform init` falla con un error de proveedor

Síntoma: terraform init en workshop_public/snowflake_migration_lab/01-setup-snowflake/ falla al resolver un proveedor.
Causa: el binario de Terraform es antiguo o no hay acceso de red al registro de Terraform.
Solución: usa Terraform >= 1.6 y confirma que tienes acceso a Internet al registro.

`snowsql` rechaza la conexión

Síntoma: snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} rechaza la conexión.
Causa: SNOWFLAKE_ORG o SNOWFLAKE_ACCOUNT es incorrecto.
Solución: vuelve a comprobar ambos valores con la cuenta que creaste y repite el mismo comando snowsql.

`dbt run` falla con `relation not found`

Síntoma: dbt run en el proyecto dbt de la Parte 1 informa de una relación que no existe.
Causa: nunca se creó la estructura de la base de datos.
Solución: ejecuta primero ./setup.sh --skip-seed y confirma que profiles.yml apunta a NYC_TAXI_DB.

Superset muestra `connection refused`

Síntoma: la interfaz de Superset de la Parte 1 rechaza la conexión justo después de docker-compose up.
Causa: Superset tarda unos 60 segundos en inicializarse.
Solución: espera 60 segundos e inténtalo de nuevo. Si sigue fallando, consulta docker logs nyc_taxi_superset.

La carga de datos tarda más de lo esperado

Síntoma: el paso de carga inicial en workshop_public/snowflake_migration_lab/01-setup-snowflake/ parece bloqueado.
Causa: a esta escala es un comportamiento normal de Snowflake, no un bloqueo. La inserción TABLE(GENERATOR) que genera 50 millones de filas tarda unos 10-12 minutos, y el UPDATE posterior que rellena la columna VARIANT TRIP_METADATA en las 50 millones de filas tarda otros 15-20 minutos con un warehouse SMALL.
Solución: deja que termine. Ninguno de los dos pasos es interactivo; no hay nada que reintentar.

Aprovisionar ClickHouse Cloud y migrar los datos

La autenticación de Terraform falla con 401 Unauthorized

Síntoma: la aplicación de Terraform en workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ falla con 401 Unauthorized.
Causa: CLICKHOUSE_TOKEN_KEY o CLICKHOUSE_TOKEN_SECRET es incorrecto, o la clave no tiene el alcance necesario.
Solución: vuelve a generar el par de claves desde la interfaz de ClickHouse Cloud, en Settings -> API keys, y asegúrate de que tenga alcance Admin.

El script de migración falla a mitad de la ejecución

Síntoma: scripts/02_migrate_trips.py se detiene durante la copia de los 50 millones de filas.
Causa: interrupciones transitorias de la red o del warehouse durante una transferencia larga.
Solución: vuelve a ejecutarlo con --resume. El script usa como marca de agua el max(pickup_at) que ya existe en ClickHouse y omite las filas que ya ha cargado:
```
python scripts/02_migrate_trips.py --resume
```

Error de conexión del script de migración

Síntoma: el script de migración no puede acceder a Snowflake o ClickHouse.
Causa: una o más variables de entorno de Snowflake o ClickHouse no están definidas en el shell actual.
Solución: compruébalas y vuelve a cargar los archivos de estado antes de reintentarlo:
```
echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD
```
Ejecuta primero source .env && source .clickhouse_state y vuelve a intentarlo.

`dbt run` falla con `Connection refused` o `Unknown host`

Síntoma: dbt run contra el proyecto de ClickHouse no puede resolver el host o conectarse a él.
Causa: CLICKHOUSE_HOST no está definido en el shell actual.
Solución: ejecuta source .clickhouse_state desde el directorio del módulo y vuelve a ejecutar dbt run.

`dbt` falla con `Could not find profile named 'nyc_taxi_ch'`

Síntoma: dbt debug o dbt run en workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch falla de inmediato porque falta el perfil.
Causa: el perfil dbt de ClickHouse nunca se añadió a ~/.dbt/profiles.yml.
Solución: abre workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example e incorpora su bloque nyc_taxi_ch: a tu ~/.dbt/profiles.yml actual como segundo perfil de nivel superior. No sobrescribas el archivo: hacerlo elimina el perfil nyc_taxi: del módulo 01 y rompe su bucle de actualización del Paso 4. Consulta 03 Aprovisionamiento y migración, donde se explica por completo este paso de combinación.

dbt en ClickHouse

`analytics.agg_hourly_zone_trips` está vacía después de ejecutar dbt

Síntoma: tras el dbt run del módulo 04, analytics.agg_hourly_zone_trips tiene cero filas y los gráficos del panel que dependen de ella no muestran datos.
Causa: es lo esperado, no un fallo. El filtro incremental del modelo es WHERE pickup_at >= now() - INTERVAL 2 HOUR, que solo coincide con las filas escritas por el productor de viajes en vivo. Todas las filas trasladadas por el script de migración son históricas, por lo que ninguna cae dentro de esa ventana de dos horas.
Solución: no hay nada que corregir. Cero es el valor correcto aquí. La tabla se llena cuando el productor empieza a escribir directamente en ClickHouse después del paso de cambio de sistema de 05 Benchmark y cambio de sistema.

Paneles y benchmark

Superset muestra 403 Forbidden

Síntoma: la interfaz de Superset devuelve 403 Forbidden durante el módulo.
Causa: la cookie de sesión ha caducado.
Solución: cierra sesión, vuelve a iniciarla en http://localhost:8088 y ejecuta de nuevo bash superset/add_clickhouse_connection.sh.

El benchmark muestra `N/A` para Q7

Síntoma: el CSV generado por run_benchmark.sh contiene N/A en lugar de un valor de aceleración para la consulta 7.
Causa: el script del benchmark no pudo conectarse a ClickHouse.
Solución: confirma que CLICKHOUSE_HOST está definido (source .clickhouse_state) y que el servicio está activo; después, vuelve a ejecutar el benchmark.

Un panel de Superset importado no se conecta a ClickHouse

Síntoma: los paneles importados en Superset se cargan, pero sus gráficos no pueden acceder a ClickHouse.
Causa: el ZIP de exportación incluido en el repositorio tiene el host anonimizado como your-instance.clickhouse.cloud. add_clickhouse_connection.sh sustituye el URI real a partir de .env antes de importarlo; una importación manual desde la interfaz de Superset no lo hace.
Solución: usa bash superset/add_clickhouse_connection.sh en vez de una importación manual, o modifica después la conexión para que use tu CLICKHOUSE_HOST y tus credenciales reales.

Cambio de sistema y paridad

La comprobación de paridad falla o parece que se pierden filas durante el cambio

Síntoma: falla la comprobación de paridad del recuento de filas del módulo 05 o parece que se han perdido datos durante el cambio.
Causa: se omitió la pasada de puesta al día con --resume. El productor de Snowflake escribe continuamente durante los módulos 01-05, por lo que la migración del módulo 03 solo capturó un prefijo de los datos; el tramo final solo existe en Snowflake hasta que se sincroniza. Detener antes de tiempo el productor de Snowflake (por ejemplo, justo después del módulo 01) destruye silenciosamente la demostración del cambio de este módulo, pues ya no queda ningún tramo por sincronizar.
Solución: ejecuta la pasada de puesta al día antes de comprobar la paridad. Solo transfiere las filas pendientes y tarda entre segundos y minutos, no los 40-50 minutos iniciales:
```
python scripts/02_migrate_trips.py --resume
bash scripts/01_verify_migration.sh
```