Solução de problemas

Uma referência de sintomas, causas e correções para as falhas encontradas pelos participantes durante este laboratório, agrupadas pelo local em que aparecem.

Todas as entradas abaixo correspondem a falhas reais: as onze documentadas nos próprios READMEs das partes do laboratório e mais cinco encontradas durante a criação e os testes deste workshop. Localize seu sintoma, leia a causa e aplique a correção. Se nada aqui corresponder ao problema, as seções ## Falhas comuns da trilha do instrutor abordam com mais detalhes o lado do facilitador em cada módulo; depois disso, procure seu arquiteto de soluções.

Ferramentas e preparação

Falha do `dbt` com erro de importação do `mashumaro` ou durante a instalação

Sintoma - a instalação de dbt-snowflake ou dbt-clickhouse falha, ou o dbt gera um erro de importação que menciona mashumaro e aparentemente não tem relação com sua versão do Python.
Causa - dbt-snowflake e dbt-clickhouse exigem Python 3.11, 3.12 ou 3.13. O Python 3.14 ou posterior quebra a dependência compartilhada mashumaro, e a falha geralmente aparece em um módulo sem relação com o problema, depois que a escolha incorreta já foi feita.
Correção - instale a versão 3.13 ao lado do Python do sistema (por exemplo, brew install python@3.13) e recrie o ambiente virtual explicitamente com esse interpretador: python3.13 -m venv .venv.

Ambiente Snowflake de origem

Falha do `terraform init` com erro de provedor

Sintoma - o terraform init em workshop_public/snowflake_migration_lab/01-setup-snowflake/ falha ao resolver um provedor.
Causa - o binário do Terraform é antigo ou não há acesso à rede para consultar o registro do Terraform.
Correção - use Terraform >= 1.6 e confirme que há acesso à Internet para consultar o registro.

Conexão recusada pelo `snowsql`

Sintoma - snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} recusa a conexão.
Causa - SNOWFLAKE_ORG ou SNOWFLAKE_ACCOUNT está incorreto.
Correção - confira novamente os dois valores na conta que você criou e repita o mesmo comando snowsql.

Falha do `dbt run` com `relation not found`

Sintoma - o dbt run no projeto dbt da Parte 1 informa que uma relação não existe.
Causa - a estrutura do banco de dados nunca foi criada.
Correção - primeiro execute ./setup.sh --skip-seed e confirme que profiles.yml aponta para NYC_TAXI_DB.

O Superset exibe `connection refused`

Sintoma - a interface do Superset na Parte 1 recusa a conexão logo após docker-compose up.
Causa - o Superset leva cerca de 60 segundos para ser inicializado.
Correção - aguarde 60 segundos e tente novamente. Se ainda houver falha, verifique docker logs nyc_taxi_superset.

A carga inicial de dados demora mais que o esperado

Sintoma - a etapa de carga inicial em workshop_public/snowflake_migration_lab/01-setup-snowflake/ parece travada.
Causa - esse comportamento do Snowflake é normal nessa escala; não se trata de um travamento. O insert com TABLE(GENERATOR), que produz 50 milhões de linhas, leva cerca de 10 a 12 minutos, e o UPDATE seguinte, que preenche a coluna VARIANT TRIP_METADATA em todas as 50 milhões de linhas, leva outros 15 a 20 minutos em um warehouse SMALL.
Correção - deixe o processo terminar. Nenhuma das etapas é interativa e não há nada a repetir.

Provisionamento do ClickHouse Cloud e migração dos dados

Falha de autenticação do Terraform com 401 Unauthorized

Sintoma - a aplicação do Terraform em workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ falha com 401 Unauthorized.
Causa - CLICKHOUSE_TOKEN_KEY ou CLICKHOUSE_TOKEN_SECRET está incorreto, ou a chave não tem o escopo necessário.
Correção - gere novamente o par de chaves na interface do ClickHouse Cloud, em Settings -> API keys, e garanta que tenha o escopo Admin.

Falha do script de migração durante a execução

Sintoma - scripts/02_migrate_trips.py é encerrado durante a cópia das 50 milhões de linhas.
Causa - instabilidades temporárias na rede ou no warehouse durante uma transferência de longa duração.
Correção - execute novamente com --resume. O script usa como marca-d'água o max(pickup_at) já presente no ClickHouse e ignora as linhas que já foram carregadas:
```
python scripts/02_migrate_trips.py --resume
```

Erro de conexão do script de migração

Sintoma - o script de migração não consegue acessar o Snowflake ou o ClickHouse.
Causa - uma ou mais variáveis de ambiente do Snowflake ou do ClickHouse não estão definidas no shell atual.
Correção - verifique-as e carregue novamente os arquivos de estado antes de tentar outra vez:
```
echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD
```
Primeiro execute source .env && source .clickhouse_state e depois tente novamente.

Falha do `dbt run` com `Connection refused` ou `Unknown host`

Sintoma - o dbt run no projeto do ClickHouse não consegue resolver um host ou se conectar a ele.
Causa - CLICKHOUSE_HOST não está definido no shell atual.
Correção - execute source .clickhouse_state no diretório do módulo e tente novamente executar dbt run.

Falha do `dbt` com `Could not find profile named 'nyc_taxi_ch'`

Sintoma - dbt debug ou dbt run em workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch falha imediatamente com um erro de perfil ausente.
Causa - o perfil dbt do ClickHouse nunca foi adicionado a ~/.dbt/profiles.yml.
Correção - abra workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example e mescle o bloco nyc_taxi_ch: ao seu ~/.dbt/profiles.yml existente como um segundo perfil de nível superior. Não sobrescreva o arquivo - isso excluiria o perfil nyc_taxi: do módulo 01 e quebraria o ciclo de atualização da Etapa 4. Consulte 03 Provisionamento e migração, que explica essa mesclagem por completo.

dbt no ClickHouse

`analytics.agg_hourly_zone_trips` está vazia após a execução do dbt

Sintoma - depois do dbt run do módulo 04, analytics.agg_hourly_zone_trips tem zero linhas e qualquer gráfico de dashboard baseado nela não exibe dados.
Causa - isso é esperado, não uma falha. O filtro incremental do modelo é WHERE pickup_at >= now() - INTERVAL 2 HOUR, que corresponde apenas às linhas gravadas pelo produtor ativo de corridas. Todas as linhas transferidas pelo script de migração são históricas, portanto nenhuma entra nessa janela de 2 horas.
Correção - não há nada a corrigir. Zero é o valor correto aqui. A tabela começa a ser preenchida quando o produtor passa a gravar diretamente no ClickHouse após a virada de 05 Benchmark e virada.

Dashboards e benchmark

O Superset exibe 403 Forbidden

Sintoma - a interface do Superset retorna 403 Forbidden durante o módulo.
Causa - o cookie de sessão expirou.
Correção - saia, entre novamente em http://localhost:8088 e execute outra vez bash superset/add_clickhouse_connection.sh.

O benchmark exibe `N/A` para Q7

Sintoma - o CSV de saída de run_benchmark.sh contém N/A no lugar do ganho de velocidade da consulta 7.
Causa - o script de benchmark não conseguiu se conectar ao ClickHouse.
Correção - confirme que CLICKHOUSE_HOST está definido (source .clickhouse_state) e que o serviço está em execução; depois, execute o benchmark novamente.

Um dashboard importado do Superset não se conecta ao ClickHouse

Sintoma - os dashboards importados no Superset são carregados, mas seus gráficos não conseguem acessar o ClickHouse.
Causa - o host no arquivo ZIP de exportação incluído no repositório foi substituído por your-instance.clickhouse.cloud. add_clickhouse_connection.sh insere a URI real a partir de .env antes da importação; uma importação manual pela interface do Superset não faz isso.
Correção - use bash superset/add_clickhouse_connection.sh em vez de uma importação manual ou, depois de importar, edite a conexão para usar seu CLICKHOUSE_HOST e suas credenciais reais.

Virada e paridade

A verificação de paridade falha ou a virada parece perder linhas

Sintoma - a verificação da paridade da contagem de linhas no módulo 05 falha, ou a virada parece ter perdido dados.
Causa - a passagem de recuperação com --resume foi ignorada. O produtor do Snowflake grava continuamente durante os módulos de 01 a 05, portanto a migração do módulo 03 capturou apenas um prefixo dos dados; o trecho final existe somente no Snowflake até ser recuperado. Interromper o produtor do Snowflake antes da hora (por exemplo, logo após o módulo 01) elimina silenciosamente a demonstração da virada deste módulo, pois não resta nenhum trecho final para recuperar.
Correção - execute a passagem de recuperação antes de verificar a paridade. Ela transfere somente as linhas da lacuna e leva de segundos a minutos, não os 40 a 50 minutos originais:
```
python scripts/02_migrate_trips.py --resume
bash scripts/01_verify_migration.sh
```