> For the complete documentation index, see [llms.txt](https://docs.adapta.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adapta.org/skip/comece-aqui/diagnostico-e-resolucao-de-erros.md). # 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. {% hint style="info" %} **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. {% endhint %} ### 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. {% hint style="success" %} **Próximo passo:** Aprenda a gerenciar sua identidade e sua equipe no Skip em [**Gestão de Conta e Organização**](/skip/comece-aqui/gestao-de-conta-e-organizacao.md). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.adapta.org/skip/comece-aqui/diagnostico-e-resolucao-de-erros.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.