Travou? Problemas comuns e como resolver
Os bloqueios que mais aparecem na implantação da Nekt, reunidos a partir de centenas de conversas de onboarding. Para cada um: como ele aparece, por que acontece e o que fazer.
- Reconhecer o problema pelo sintoma
- Resolver sozinho os casos mais comuns, sem esperar uma call
- Saber quando chamar o time da Nekt e o que mandar
A maior parte do que trava uma implantação não é dúvida de produto. É uma credencial que ninguém tem à mão, um banco que não aceita conexão de fora, uma pessoa que precisava estar na configuração e não estava. A boa notícia: quase tudo tem um caminho conhecido. Ache o seu sintoma abaixo.
Se algo falhou, abra o run na página Runs e leia o resumo do analista: a Nekt explica, em linguagem simples, o que aconteceu e o que fazer. Ele resolve boa parte dos casos sem precisar deste guia. Se você usa a Nekt pelo Claude ou ChatGPT com o MCP, peça para a IA ler o log da execução que falhou.
1. Credencial recusada ou ninguém tem o acesso
Por que acontece:
- A credencial foi colada errada: espaço no fim da senha, chave cortada, token de outra conta.
- O token ou a autorização OAuth expirou ou foi revogado.
- A conta usada não tem permissão suficiente na ferramenta de origem (precisa ser administradora ou ter acesso à API).
- Quem tem o acesso não está participando da configuração.
O que fazer:
- Use o Share setup link. Ao adicionar a fonte (Sources → Add source → escolha o conector), clique em Share setup link na etapa de acesso e mande o link para quem tem a credencial: TI, administrador da conta ou, numa agência, o próprio cliente. A pessoa não precisa de conta na Nekt, preenche os campos ou faz o login, e a senha nunca passa por e-mail ou chat. O link vale 24 horas; depois disso, gere outro no mesmo rascunho.
- Autorização expirada: reconecte a conta na página da fonte e reprocesse.
- Confira se a conta conectada tem papel de administrador ou acesso à API.
- Ao colar senha ou chave, cole o valor inteiro, sem espaços antes ou depois.
2. Banco de dados não conecta
Por que acontece: o banco não aceita conexões vindas da Nekt. Ou o firewall não libera o IP da Nekt, ou o banco está numa rede interna sem acesso de fora.
O que fazer:
- Libere no firewall o IP público da Nekt. Ele aparece na seção Helpful resources da tela de configuração da fonte.
-
Se o banco não pode ficar exposto à internet, use um
túnel SSH: uma máquina pequena (VM) que alcança o
banco e aceita conexão SSH. Os conectores de banco (Postgres,
MySQL, SQL Server, Oracle, Firebird, SAP HANA e outros) têm os
campos SSH Host, SSH Port (padrão 22), SSH Username e SSH Password
ou SSH Private Key. Com túnel, o host do banco costuma ser
127.0.0.1. -
A chave privada precisa estar em formato PEM (Ed25519, ECDSA ou
RSA). Cole o bloco inteiro, do
-----BEGINao-----END. - Banco na AWS sem acesso público: VPC peering é uma opção. Fale com o time da Nekt.
Chave colada pela metade é a causa mais comum de túnel que não sobe. E prefira túnel SSH a VPN para uma conexão que fica de pé o tempo todo: VPN costuma cair mais. Quem mexe em rede costuma ser TI ou um fornecedor externo, então marque a configuração com essa pessoa junto.
3. O conector que preciso não existe
Do mais simples ao mais trabalhoso:
| Caminho | Quando usar |
|---|---|
| REST API genérico | O sistema tem API. Você informa a URL base, a autenticação (token, API key, OAuth e outras) e a paginação. |
| Webhook | O sistema consegue enviar eventos quando algo acontece. |
| Google Sheets ou CSV | Ponte temporária para dados que hoje vivem em planilha ou exportação. |
| Notebook em Python | Chamar uma API com lógica própria. |
| Pedir o conector | Conte ao time da Nekt qual sistema e quais dados você precisa; ele avalia e prioriza. |
Comece pelo caso de uso. Muitas vezes só duas ou três tabelas do sistema importam, e uma ponte simples resolve até o conector existir.
4. Fonte conectada, tabelas vazias
Por que acontece: ainda não houve uma execução com sucesso. As tabelas aparecem no catálogo assim que a fonte é configurada, mas os dados só chegam depois da primeira carga concluída.
O que fazer: veja o histórico de execuções da fonte. Se a primeira carga ainda está rodando, espere: em fontes grandes ela pode levar horas. Se falhou, vá para o item 6.
5. Coluna nova ou dado apagado não aparece
- Colunas novas: se a fonte sincroniza todos os campos, colunas novas entram sozinhas ("Auto-add fields"). No sync incremental, só as linhas novas vêm com a coluna preenchida. Para preencher o histórico, rode um full sync.
- Registros apagados na origem continuam no lake até um full sync. Se isso importa, agende um Additional Full Sync semanal ou mensal.
- Tabela que não aceita incremental: o incremental depende de um campo que diga quando cada registro mudou. Se a API não oferece esse campo, só full sync é possível.
Mais detalhes no guia Sync types: full vs incremental.
6. Execução falhou ou pipeline desativado
- Abra o run que falhou na página Runs e leia o resumo do analista: o que aconteceu e as ações recomendadas.
- Siga as ações na ordem e reprocesse.
- Pipeline desativado sozinho: cada pipeline tem, na aba Settings, um limite de Max consecutive failures. Ao atingir esse limite, ele é desativado. Corrija a causa e reative pelo trigger (Details → Trigger → Edit trigger).
- Se a fonte fica fora do ar em certos horários (um banco que desliga no fim de semana, por exemplo), agende só nos dias e horários em que ela está disponível.
- Falha num pipeline que depende de outro costuma ser efeito cascata: corrija a origem primeiro.
- Ative alertas nos pipelines importantes: o botão Alerts na página do recurso, ou alertas globais em Settings → Alerts.
Mais detalhes no guia Monitorando pipelines e runs.
7. Limite de requisições da API
O que fazer: reduza o volume por execução. Muitos conectores têm opções como janela de dias (lookback), requisições por minuto e paralelismo: comece conservador e aumente aos poucos. Evite sincronizar com frequência maior do que a decisão precisa e prefira o incremental.
8. MCP não conecta ou a IA não vê as tabelas
| Causa | O que fazer |
|---|---|
| O MCP não está habilitado | Na Nekt, clique em MCP no canto superior direito → Manage MCP Gateway → Enable now. O MCP Server faz parte dos planos pagos. |
| A ferramenta de IA não aceita conector personalizado no seu plano | Claude (conector personalizado, no app ou no navegador) e ChatGPT (Plus, Team ou Enterprise) estão documentados; Cursor, Codex e outros conectam por token. Versões de consumo de algumas IAs não aceitam conectores personalizados: confirme no seu plano antes. |
| Login com a conta errada | A conexão herda as permissões de quem criou o token. Refaça a conexão com a conta certa. Se quem criou o token saiu do workspace, ele para de funcionar. |
| Token com escopo restrito | Tokens de escopo personalizado só enxergam o que foi liberado e não alcançam fontes, transformações, execuções nem alertas. Edite o token em Access tokens ou use um de acesso completo durante a implantação. |
| Permissão de dados | No plano Growth, as permissões valem também para a IA. Confira em Workspace → Permissions. |
| Os dados ainda não carregaram | Veja o item 4. |
Para ver qual token está em uso: Access tokens → View token access.
9. A IA responde errado
Por que acontece: quase sempre falta contexto do negócio. A IA não sabe o que conta como cliente ativo, venda ou lead qualificado, nem qual tabela é a oficial.
- Escreva um documento de contexto com as definições e regras do seu caso de uso, e atualize toda vez que uma resposta sair errada por causa de uma regra.
- Teste com perguntas cuja resposta você já conhece antes de confiar em perguntas novas.
- Para perguntas recorrentes, salve a consulta como tabela pronta na camada Gold e aponte a IA para ela: fica mais rápido e consistente.
- Vários documentos curtos e focados funcionam melhor que um documento enorme.
10. Créditos acima do esperado
Como funciona: 1 crédito = 1 execução de pipeline (fonte, consulta, notebook, history ou destino). Não há cobrança por linha, por número de conectores ou por usuário. Execuções que falham e a carga inicial de uma fonte não consomem créditos. O consumo aparece em Settings → Billing.
Por que veio alto: quase sempre frequência. Uma fonte que roda de hora em hora executa 168 vezes por semana; uma diária, 7.
- Escolha a frequência pela decisão: se o relatório é olhado uma vez por dia, atualizar uma vez por dia basta.
- Rode só em dias e horários úteis se ninguém usa o dado no fim de semana.
- Encadeie transformações por evento (rodar quando a fonte terminar) em vez de horários fixos.
- Desligue pipelines que ninguém usa mais.
Mais detalhes no guia Triggers e agendamento sem desperdício.
11. Quando chamar o time da Nekt
Chame quando o erro volta depois de corrigir a configuração, quando você precisa de um conector novo, quando envolve plano ou cobrança, ou quando algo só pode ser feito pelo time da Nekt. Para resolver mais rápido, mande junto:
- o nome da fonte ou do recurso;
- o que você já tentou;
- a mensagem de erro;
- o link do run, se houver.
Nunca envie senhas ou tokens por chat ou e-mail.