Solução de problemas

Uma referência com sintoma, causa e correção para todas as falhas observadas durante a criação e os testes deste workshop, agrupadas pelo local em que aparecem.

Os comandos desta página usam os valores salvos em .env.workshop.

Cada item abaixo corresponde a uma falha que realmente ocorreu durante a criação e os testes deste workshop. Encontre seu sintoma, entenda a causa e aplique a correção. Se nada corresponder ao seu caso, passe o problema para seu agente de programação — o guia para fazer o workshop no seu próprio ritmo contém um prompt pronto para colar que transforma o agente em seu instrutor.

Windows e WSL 2

`wsl --install` não está disponível ou apenas exibe a ajuda

Sintoma — o PowerShell como administrador não reconhece wsl --install, ou exibe a ajuda em vez de instalar o Ubuntu.
Causa — a versão do Windows é inferior ao mínimo exigido pelo workshop, atualizações pendentes não foram aplicadas ou a política corporativa desativa o WSL.
Correção — execute o Windows Update e confirme se você usa o Windows 11 ou o Windows 10 versão 2004 (build 19041) ou posterior. Reinicie e siga as etapas de instalação manual do WSL da Microsoft. Em um computador gerenciado, um administrador precisa permitir os recursos necessários do Windows.

Um comando “não é reconhecido” no PowerShell

Sintoma — o PowerShell rejeita ./preflight.sh, export, source ou outro comando Bash do workshop.
Causa — a configuração do Windows usa o PowerShell apenas para a inicialização do WSL identificada explicitamente. Os comandos do workshop são executados dentro do Ubuntu no WSL 2.
Correção — abra o Ubuntu pelo menu Iniciar, volte ao diretório do aplicativo e execute a verificação prévia ali:
```
cd ~/ClickHouse_Demos/workshops/build_workshop/app
./preflight.sh
```

O repositório está em `/mnt/c`

Sintoma — as montagens vinculadas do Docker estão lentas, os scripts apresentam falhas de permissão ou fim de linha, ou o caminho do repositório começa com /mnt/c/Users/....
Causa — o repositório foi clonado no sistema de arquivos do Windows, em vez do sistema de arquivos Linux do WSL.

Correção — mantenha a cópia antiga somente se precisar de trabalho ainda não adicionado ao repositório. Caso contrário, abra o Ubuntu e clone uma cópia limpa no seu diretório pessoal do Linux:

cd ~
git config --global core.autocrlf input
git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd workshops/build_workshop/app
cp .env.workshop.example .env.workshop

O Ubuntu está sendo executado como WSL 1

Sintoma — wsl --list --verbose mostra o Ubuntu com VERSION 1, ou o Docker Desktop não consegue integrar-se à distribuição.
Causa — a distribuição é anterior ao WSL 2 ou foi instalada com o WSL 1 como padrão.
Correção — abra o PowerShell como administrador, converta a distribuição e reabra o Ubuntu:
```
wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --list --verbose
```

`docker` não está disponível dentro do Ubuntu

Sintoma — o Docker Desktop está em execução, mas o Ubuntu mostra docker: command not found ou não consegue acessar o daemon.
Causa — o mecanismo WSL do Docker Desktop ou a integração com o Ubuntu está desativada.
Correção — ative Docker Desktop -> Settings -> General -> Use the WSL 2 based engine e Resources -> WSL Integration -> Ubuntu, aplique a alteração e execute wsl --shutdown no PowerShell. Depois, reabra o Ubuntu. docker version deve mostrar as seções Client e Server.

O WSL ou o Docker tem menos de 6 GB de memória

Sintoma — a verificação prévia informa memória insuficiente, ou docker info --format 'Docker memory: {{.MemTotal}} bytes' exibe menos de 6442450944 bytes.
Causa — o back-end WSL 2 do Docker Desktop usa o limite de memória da máquina virtual do WSL.
Correção — feche o Docker Desktop, abra o PowerShell e crie um limite de 8 GB para o WSL:
```
@('[wsl2]', 'memory=8GB', 'processors=4') |
  Set-Content -Encoding ascii "$env:USERPROFILE\.wslconfig"
wsl --shutdown
```
Inicie o Docker Desktop e reabra o Ubuntu. Execute novamente o comando docker info e a verificação prévia.

Um script informa `/usr/bin/env: 'bash\r': No such file or directory`

Sintoma — um arquivo .sh falha imediatamente, e o erro inclui bash\r ou ^M.
Causa — os fins de linha CRLF do Windows substituíram os fins de linha LF exigidos pelo repositório.
Correção — no Ubuntu, defina a política do Git para o WSL e restaure um checkout limpo:
```
git config --global core.autocrlf input
git status --short
git add --renormalize .
```
Revise git status antes de descartar ou adicionar qualquer coisa. Se o checkout não tiver nenhum trabalho necessário, um clone limpo em ~/ClickHouse_Demos é a forma mais segura de recuperar o ambiente.

O OAuth não abre o navegador do Windows

Sintoma — um login do MCP exibe uma URL, mas nenhuma janela do navegador é aberta.
Causa — o agente de programação está sendo executado dentro do WSL, e o encaminhamento para o navegador não está disponível ou foi bloqueado pela política corporativa.
Correção — copie a URL de login completa do Ubuntu e cole-a no navegador normal do Windows. Conclua a autorização ali e volte ao terminal do Ubuntu.

Docker

Os contêineres ficam presos em “Created” e nunca iniciam

Sintoma — docker info responde normalmente, mas docker compose ... up deixa os contêineres em Created, e nenhum deles fica íntegro.
Causa — o mecanismo do Docker está travado: o daemon responde, mas não consegue iniciar um contêiner. Isso foi observado com o OrbStack durante uma inicialização ao vivo.
Correção — reinicie o mecanismo do Docker (Docker Desktop, OrbStack ou Colima) e aguarde até ele informar Running. Depois, inicie a pilha novamente. De qualquer lugar dentro do repositório clonado, execute cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh; o script detecta esse problema antes da inicialização da pilha, executando um contêiner descartável como teste.

“port is already allocated” durante a inicialização

Sintoma — docker compose ... up falha com Bind for 0.0.0.0:8080 failed: port is already allocated (ou :8000).
Causa — outro processo ou um contêiner antigo do workshop já ocupa essa porta do host.
Correção — de qualquer lugar dentro do repositório clonado, execute cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh. O script identifica o que está ocupando a porta e exibe a substituição exata a ser definida, seguindo a convenção de porta-base + 20000, por exemplo, set FRONTEND_HOST_PORT=28080 in .env.workshop. As variáveis de substituição são FRONTEND_HOST_PORT, BACKEND_HOST_PORT e, para a sobreposição de observabilidade, OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT. Defina o valor sugerido, execute novamente a verificação prévia e inicie a pilha. Somente as portas do host mudam; as portas dentro dos contêineres permanecem iguais, portanto a alteração é segura.

Aviso “platform does not match”

Sintoma — o Docker exibe um aviso de incompatibilidade de plataforma (por exemplo, linux/amd64 em vez de linux/arm64) ao baixar ou iniciar uma imagem.
Causa — uma imagem foi criada para uma arquitetura de CPU diferente da arquitetura do seu computador, algo comum no Apple Silicon.
Correção — não há problema. É um aviso, não uma falha; a imagem é executada por emulação. Deixe o processo continuar.

ClickHouse Cloud

A primeira solicitação após um período de inatividade fica lenta ou retorna 500 uma vez

Sintoma — a primeira consulta ou o primeiro carregamento do painel após um período de inatividade do serviço fica lento, ou uma solicitação retorna 500 uma vez e depois funciona.
Causa — um serviço na nuvem reduz a escala a zero quando está ocioso e leva cerca de 30 segundos para reativar; a primeira solicitação paga esse custo. O back-end já permite um timeout maior na primeira conexão e faz uma nova tentativa.
Correção — tente novamente ou aguarde cerca de 30 segundos. Isso não é uma falha. Também é relevante em 07 Testar, falhar e corrigir: um serviço em processo de reativação aumenta a probabilidade de a falha 03 atingir o timeout.

A senha do serviço foi perdida

Sintoma — você não salvou a senha do usuário default e não consegue encontrá-la.
Causa — a senha do serviço não volta a ser exibida depois que você sai do fluxo de criação.
Correção — abra o serviço, acesse Settings e redefina a senha do usuário default; depois, atualize CLICKHOUSE_PASSWORD em .env.workshop. O host sempre está disponível na janela Connect.

A senha do Postgres gerenciado foi perdida

Sintoma — você não salvou a senha de administrador de uso único do usuário postgres retornada por clickhousectl cloud postgres create.
Causa — ela é exibida uma única vez, e as APIs beta postgres get / list podem retornar vazio ou FORBIDDEN mesmo quando a instância está íntegra.
Correção — execute clickhousectl cloud postgres reset-password <service-id> e use a nova senha em .env.workshop (PGPASSWORD) e na conexão do ClickPipe.

O ClickHouse Cloud não está acessível

Sintoma — a verificação prévia marca a conectividade como FAIL, ou o back-end não consegue se conectar; the command below falha.

CLICKHOUSE_HOST=$(sed -n 's/^CLICKHOUSE_HOST=//p' .env.workshop | tail -n 1)
CLICKHOUSE_PORT=$(sed -n 's/^CLICKHOUSE_PORT=//p' .env.workshop | tail -n 1)
curl "https://$CLICKHOUSE_HOST:$CLICKHOUSE_PORT/ping"

Causa — Wi-Fi, VPN ou firewall; host incorreto (um esquema ou uma porta foi colado em CLICKHOUSE_HOST); incompatibilidade de TLS ou porta; ou uma lista de acesso por IP do Cloud bloqueando seu endereço.
Correção — confirme se CLICKHOUSE_HOST contém apenas o nome do host (sem https:// e sem porta), CLICKHOUSE_PORT=8443 e CLICKHOUSE_SECURE=true; confira a VPN e o firewall; confirme se a lista de acesso por IP do serviço permite seu endereço. A verificação prévia identifica a falha específica — DNS, conexão recusada, timeout ou handshake TLS.

O cliente exibe `Unknown settings: ... skipping`

Sintoma — as consultas funcionam, mas cada execução exibe um aviso de configuração desconhecida.
Causa — o cliente instalado localmente é mais recente que o servidor na nuvem e envia uma configuração que essa versão do servidor não reconhece.
Correção — repita os comandos para instalar o cliente correspondente da etapa 6 do módulo 00. Eles leem a versão do servidor na nuvem por meio de clickhousectl e selecionam a versão principal/secundária correspondente do cliente. Não oculte todos os avisos do cliente com --no-warnings.

CDC (módulo 03)

A criação do ClickPipe informa `table realtime_trips exists and is not empty`

Sintoma — não existe um recurso ClickPipe, mas recriá-lo falha porque default.realtime_trips já contém linhas.
Causa — a exclusão de um ClickPipe remove seu slot de replicação na origem, mas pode deixar a tabela de destino. Um novo pipe não substituirá essa tabela se ela não estiver vazia.

Correção — preserve as linhas brutas antigas usando nomes de backup com carimbo de data e hora e recrie o pipe. Substitua o espaço reservado do ID do serviço uma única vez; estes comandos também preservam a view materializada antiga, caso exista:

CH_SERVICE_ID=<clickhouse-service-id>
BACKUP_SUFFIX=$(date -u +%Y%m%d%H%M%S)

if clickhousectl cloud service query --id "$CH_SERVICE_ID" \
  --query "EXISTS TABLE nyc_tlc_data.realtime_trips_to_taxi_trips_mv" | grep -q 1; then
  clickhousectl cloud service query --id "$CH_SERVICE_ID" --query "
    RENAME TABLE nyc_tlc_data.realtime_trips_to_taxi_trips_mv
    TO nyc_tlc_data.realtime_trips_to_taxi_trips_mv_backup_${BACKUP_SUFFIX}
  "
fi

clickhousectl cloud service query --id "$CH_SERVICE_ID" --query "
  RENAME TABLE default.realtime_trips
  TO default.realtime_trips_backup_${BACKUP_SUFFIX}
"

Execute novamente a etapa 3 do módulo 03 e aguarde a nova tabela default.realtime_trips antes de recriar a view materializada canônica na etapa 4. Exclua os backups com carimbo de data e hora mais tarde, somente depois de confirmar que não precisa mais dos dados.

O ClickPipe está preso em “Provisioning”

Sintoma — o pipe permanece em Provisioning por algum tempo depois da criação.
Causa — o snapshot e a inicialização da infraestrutura costumam levar alguns minutos, mas podem levar mais de 10 minutos mesmo para esta tabela pequena.
Correção — acompanhe o progresso no console ou usando os dois comandos clickhousectl cloud clickpipe list <clickhouse-service-id> e clickhousectl cloud clickpipe get <clickhouse-service-id> <clickpipe-id>. Durante os primeiros minutos, continue aguardando enquanto o estado ou o valor updatedAt avançar. Se ainda estiver em Provisioning sem atualização depois de 10 minutos, confirme se o log de pg-trip-writer ainda mostra inserções, confira novamente o host, as credenciais, a publicação e o mapeamento de tabelas e inspecione o erro informado pelo pipe. Não crie um segundo pipe nem a view materializada enquanto o primeiro ainda estiver sendo provisionado. Se as verificações da origem passarem e o Cloud não informar nenhum erro acionável, salve a saída de get e encaminhe o problema ao instrutor ou ao suporte do ClickHouse Cloud.

As linhas não estão chegando ao ClickHouse

Sintoma — o pipe está Running, mas a contagem de linhas no destino não aumenta, e o painel Ops não muda.
Causa — o intervalo padrão de sincronização é de aproximadamente 60 segundos, portanto há atraso; ou o gerador não está inserindo; ou a publicação lida pelo pipe não existe.
Correção — aguarde pelo menos 60 segundos. Confira se o log de pg-trip-writer mostra inserted N trips e created publication pub_taxi (em uma instância própria) ou publication ... already exists (em uma instância gerenciada de contingência fornecida pelo instrutor). Confirme se o estado do pipe é Running. Se a publicação estiver ausente, o pipe não terá o que ler — o gerador a cria na primeira execução em uma instância na qual você é administrador.

A view materializada não tem linhas

Sintoma — realtime_trips é preenchida, mas taxi_trips (alimentada pela view materializada de CDC) permanece vazia.
Causa — a view materializada foi criada antes de o destino do ClickPipe existir, ou ela não lê o destino da CLI em default.realtime_trips.
Correção — aguarde a tabela de destino e copie o comando completo da view materializada da etapa 4 do módulo 03. Primeiro, verifique a origem:
```
clickhousectl cloud service query --id <clickhouse-service-id> --query "
  SELECT database, name, engine
  FROM system.tables
  WHERE name = 'realtime_trips'
"
```
Uma view materializada processa as linhas inseridas depois de sua criação; mantenha o gravador de viagens em execução após criá-la.

O slot de replicação trava

Sintoma — o pipe trava, e o WAL cresce no Postgres de origem.
Causa — um slot travado retém o WAL; uma nova sincronização cria um novo slot.
Correção — no seu próprio Postgres gerenciado (um slot e ampla capacidade), basta sincronizar novamente o pipe pelo console. Excluir um pipe remove seu slot na origem. Qualquer conjunto gerenciado de contingência do instrutor é responsabilidade do instrutor — consulte infra/README.md.

Variáveis de ambiente

Uma variável exportada no shell substitui o .env.workshop

Sintoma — você define um valor em .env.workshop, mas o contêiner usa outro (muitas vezes um OPENAI_API_KEY, um LANGFUSE_* ou um CLICKHOUSE_PASSWORD antigo).
Causa — docker compose interpola primeiro ${VAR} do shell, e uma variável exportada no shell TEM PRECEDÊNCIA sobre o arquivo.
Correção — no shell em que você executa o Compose, unset OPENAI_API_KEY LANGFUSE_PUBLIC_KEY LANGFUSE_SECRET_KEY LANGFUSE_BASE_URL CLICKHOUSE_PASSWORD, e depois inicie novamente a pilha. A verificação prévia avisa quando detecta esse caso.

Chaves duplicadas no .env.workshop

Sintoma — um valor definido no arquivo é ignorado.
Causa — a mesma chave aparece duas vezes; a última ocorrência prevalece, de acordo com a semântica do docker compose (a verificação prévia lê o arquivo da mesma forma).
Correção — remova a ocorrência duplicada anterior para que somente o valor pretendido permaneça.

Chat (módulo 08)

POST /api/chat retorna 503 com uma orientação de configuração

Sintoma — o painel de chat mostra uma orientação de configuração, e /api/chat retorna 503; o restante do aplicativo funciona normalmente.
Causa — OPENAI_API_KEY não foi definido no back-end.
Correção — adicione OPENAI_API_KEY a .env.workshop e execute docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build backend. O chat é o único recurso que precisa dessa chave.

Não é possível criar a primeira chave da OpenAI

Sintoma — a OpenAI não emite uma chave de API para uma conta nova.
Causa — contas novas exigem uma verificação única por telefone e não têm créditos gratuitos.
Correção — conclua a verificação por telefone e acesse Settings -> Billing: adicione uma forma de pagamento e compre o mínimo de US$ 5 em créditos pré-pagos. Desative a recarga automática (ela vem ativada por padrão durante a configuração) para nunca pagar além dos US$ 5 adicionados.

MCP e OAuth (módulos 00 e 06)

Erro 401 no endpoint MCP

Sintoma — acessar https://mcp.clickhouse.cloud/mcp (ou /clickstack) retorna 401.
Causa — isso é esperado antes da conclusão do fluxo OAuth no navegador; o endpoint exige autenticação.
Correção — adicione o servidor ao agente, execute o fluxo OAuth e autorize-o no navegador usando o comando da sua ferramenta:
- Claude Code — execute /mcp, selecione o servidor e autorize-o (ou use claude mcp login <name>).
- Codex CLI — codex mcp login <name>.
- Cursor — abra o painel de configurações do MCP e clique no controle de autorização/login do servidor.
Confirme também se a opção Connect with MCP está ativada para seu serviço.

O laptop corporativo bloqueia o MCP ou o OAuth

Sintoma — seu agente não consegue adicionar um servidor MCP, ou o redirecionamento do OAuth é bloqueado.
Causa — uma política do laptop gerenciado bloqueia a adição de servidores MCP ou o OAuth de saída.
Correção — um computador pessoal é a alternativa mais rápida.

O Windsurf não consegue se conectar por HTTP nativo

Sintoma — o Windsurf não consegue se conectar ao endpoint MCP, ou o OAuth é instável.
Causa — o Windsurf se conecta por meio de mcp-remote, em vez do HTTP transmitível nativo.
Correção — use o formato de comando mcp-remote: { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"] } (troque /mcp por /clickstack ao conectar o ClickStack MCP no módulo 06).