> 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 %}