Diagnóstico e Resolução de Erros

Este guia é para quando seu app tem um problema técnico mais difícil de localizar — aquele em que o Bug Scanner sozinho não resolveu. Aqui você aprende a usar as ferramentas de diagnóstico do navegador, a ler os logs do backend e a escrever prompts de correção eficazes.

Antes de seguir os passos abaixo, sempre abra o Bug Scanner primeiro. Na maioria das vezes o erro já aparece lá e você resolve em segundos.

1. Ferramentas essenciais de diagnóstico

Antes de corrigir um erro, localize onde ele está: na interface (Frontend) ou na comunicação com o servidor (Backend / API)?

A. DevTools do navegador (F12)

Aperte F12 (ou clique com o botão direito na página → Inspecionar) para abrir as DevTools.

Aba Console

Identifique erros de lógica visual ou travamentos na interface. Mensagens em vermelho são erros; em amarelo, avisos.

Aba Network (Rede)

A ferramenta mais importante para erros de integração.

• Procure linhas vermelhas com status 400, 401 ou 500.

• Clique na requisição com erro e vá em Preview / Response — ali aparece a mensagem real retornada pelo servidor:

  • "model not found" → modelo de IA desatualizado ou inválido.

  • "invalid API key" → chave errada ou expirada.

  • "CORS error" → problema de autorização cruzada.

Essa mensagem é o ponto de partida para qualquer correção séria.

B. Logs do Backend

Se você usa Skip Cloud: Banco de Dados, Autenticação e Segredos (recomendado)

Abra o painel do projeto e vá na aba Logs.

• Se a função não estiver sendo chamada (nenhum registro novo), o problema está no envio da requisição pelo Skip, não no backend.

• Se a função foi chamada mas falhou, o log mostra a mensagem exata do erro.

Verifique também o equivalente a Table Editor / Coleções para confirmar que as tabelas e colunas foram criadas com os nomes e tipos de dados corretos.

Se você usa Supabase como alternativa

• Acesse: Console do Supabase → Functions → Logs.

• Table Editor: Confirme se as tabelas existem e têm a estrutura esperada.

2. Estratégias de prompt para pedir correções à IA

A qualidade da correção depende muito do seu vocabulário e do que você pede.

Use vocabulário técnico preciso

Quanto mais específico o termo, menos chance de ambiguidade:

• "Edge Function" em vez de "API".

• "CRUD" (Create, Read, Update, Delete) em vez de "operações básicas no banco".

• "401 Unauthorized" em vez de "está dando erro".

Debugue no Modo Chat antes de consertar

O Modo Chat (3 créditos) permite que o Skip analise tabelas, arquivos e lógica antes de implementar qualquer coisa. Usar o Chat para planejar uma correção antes de acionar o Build economiza créditos e produz resultados mais precisos.

Use comandos de restrição

Quando pedir correção, seja explícito sobre o escopo:

💬 "Corrija apenas o erro X na página Y, não altere mais nada."

Isso evita que a IA introduza novos bugs em partes já prontas do app.

3. Guia de resolução de erros comuns

🔒 Erros de autorização (CORS / 401 Unauthorized)

Muitas vezes, ao criar uma Edge Function no Supabase, a opção "Verify JWT" vem ativada por padrão. Isso exige que cada chamada à função inclua um token válido do usuário logado — algo que pode falhar em testes iniciais.

Solução:

Se a integração falhar com erro 401 ou CORS, vá ao Supabase → Functions → Escolha a função → Details e desative "Verify JWT" para testar a comunicação aberta. Depois que estiver funcionando, reative se for necessário para segurança.

🤖 Erros de integração com LLMs (Gemini / OpenAI)

Modelos desatualizados

A IA pode tentar usar modelos que não existem mais (ex.: versões antigas do Gemini 1.5 Pro que foram descontinuadas).

Solução: Sempre forneça o nome exato do modelo atualizado na documentação oficial do provedor. Ex.:

💬 "Use o modelo gemini-2.5-flash para esta integração."

API Key inválida ou sem saldo

Solução:

1. Verifique no painel de Segredos do Skip Cloud (ou em Edge Functions > Secrets, no Supabase) se a chave está correta e completa.

2. Confirme no painel do provedor (OpenAI, Gemini, etc.) se há saldo disponível e se a chave não foi revogada.

🎭 Dados "mockados" (fakes) vs. reais

Quando você começa o app, a IA costuma preencher a interface com dados fictícios para mostrar como vai ficar visualmente. Depois de conectar o banco de dados, é preciso pedir explicitamente para a IA trocar esses dados pelos reais:

💬 "O banco de dados está integrado. Substitua os dados fictícios por dados reais vindos das tabelas."

Sem esse prompt, o app pode continuar mostrando dados falsos mesmo depois de o banco estar configurado.

♾️ Loading infinito após o login

Sintoma: O usuário faz login, mas a tela fica travada em um loading que nunca termina.

Causa comum: Funções excessivamente complexas (especialmente async) dentro do callback de login, que travam o fluxo.

Soluções rápidas:

• Evite usar funções async como callbacks de autenticação.

• Limite o número de chamadas await dentro de callbacks.

• Não chame outras funções do backend dentro do callback do login. Se for absolutamente necessário, dispare essas funções depois que o callback terminar de executar.

• Dica adicional: setTimeout(() => { … }, 0) pode ser usado para garantir que a execução aconteça fora do ciclo do callback.

Vocabulário essencial

• Tabelas e colunas: Pense em tabelas como planilhas; cada linha é um registro, cada coluna é um campo.

• Row Level Security (RLS): Recurso de segurança que define quem pode ver ou alterar cada linha. Permite, por exemplo, que cada usuário só veja os próprios dados.

• Edge Functions: Funções que rodam na "borda" da rede, perto do usuário. Boas para lógica personalizada e para esconder chaves de API do frontend.

• Triggers (Gatilhos): Ações automáticas disparadas no banco quando algo acontece. Exemplo: criar um perfil automaticamente sempre que um novo usuário se cadastra.

• Deadlock: Travamento causado quando duas operações ficam esperando uma a outra indefinidamente.

Fluxo recomendado de troubleshooting

1. Bug Scanner — abra primeiro. Erros simples aparecem ali.

2. DevTools (F12) → Console e Network — para identificar onde está o problema.

3. Logs do Skip Cloud (ou Supabase) — para ver o que o backend realmente retornou.

4. Modo Chat — cole a mensagem de erro e peça análise sem gastar crédito de build.

5. Modo Build — só depois de entender o problema, peça a correção com escopo restrito.

Próximo passo: Aprenda a gerenciar sua identidade e sua equipe no Skip em Gestão de Conta e Organização.