Capítulo 06 / Quando algo trava

Problemas comuns

Catálogo de coisas que dão errado mais cedo ou mais tarde, com a saída. Dois princípios: não delete arbitrariamente — investigue antes; e nunca rode comandos destrutivos em simpe-ms-test ou simpe-ms-dev sem ter certeza absoluta.

supabase start falha por porta em uso

Algum container está com porta ocupada (54321, 54322, 54323, 54324, 54327). Provável: ficou um supabase start antigo zumbi.

Diagnóstico

lsof -i :54321  # ou ss -tlnp | grep 54321 no Linux

Correção

supabase stop

Se o stop não resolve (a CLI perdeu o tracking dos containers), derrube manualmente: 

docker ps | grep supabase | awk '{print $1}' | xargs docker stop

db:reset falhou no seed

db reset aplica todas as migrations primeiro, depois roda o seed. Se quebrou, o erro é provavelmente no seu seed.sql — FK, enum inválido, ou coluna NOT NULL sem valor.

Diagnóstico

A saída mostra a linha exata do erro. Olhe e ajuste. Lembre-se que as 100+ migrations rodam ANTES — se o erro fala de uma tabela que existe, é o seed. Se fala de algo do schema, é uma migration.

Correção

Edite supabase/seed.sql, salve, rode npm run db:reset de novo. O reset é seguro: dropa o schema antes, então não há resíduo.

Login no app não funciona

Você roda o app, tenta logar com admin@local.test, e nada.

Checklist rápido

  1. Confirme que o db:reset rodou sem erro — sem ele, não tem usuário no banco.
  2. No Studio (http://127.0.0.1:54323), tabela auth.users: os 5 usuários existem? Têm email_confirmed_at preenchido?
  3. Na tabela profiles, eles têm status_aprovado=true e ativo=true?
  4. No .env, o NEXT_PUBLIC_SUPABASE_URL está apontando para http://127.0.0.1:54321? E as chaves correspondem ao supabase status atual?

Se as chaves do .env não baterem com o supabase status atual, o app vai tentar autenticar contra um servidor que não existe mais (chaves de uma instância anterior). É a causa mais comum de "login não funciona após reinstalar".

db push reclama de drift

Você tenta promover migrations para simpe-ms-test e a CLI diz que o banco remoto tem algo que suas migrations não preveem.

Diagnóstico

supabase db diff

Mostra exatamente a divergência.

Resoluções possíveis

  • Alguém aplicou SQL direto no cloud sem migration. Crie uma migration local que absorva esse estado: supabase db pull gera uma proposta, mas revise antes de commitar.
  • Migrations divergiram entre test e dev. Geralmente alguma migration foi aplicada só em um. Confira schema_migrations nos dois e aplique as pendentes no que está atrás.

Drift entre simpe-ms-test e simpe-ms-dev

Algumas migrations existem em test mas não em dev (ou vice-versa). Sintoma típico: erro em produção que não aparece em homologação.

Diagnóstico

Compare a tabela supabase_migrations.schema_migrations entre os dois projetos via dashboard. As linhas (timestamps) diferentes apontam o que falta onde.

Correção

Linke a CLI no projeto que está atrás e rode as migrations pendentes. Se as migrations não estão no repo (alguém aplicou ad-hoc), recupere o SQL do dashboard e crie migrations corretivas no repo para garantir reprodutibilidade.

Edge function deploy falha com erro de import

Geralmente é módulo Deno faltando ou versão incompatível em supabase/deno.jsonc.

Diagnóstico

supabase functions serve nome_da_funcao

Roda local com a mesma resolução de imports do deploy. Se aqui também falha, o problema é no deno.jsonc. Se aqui passa mas o deploy não, é específico da versão remota da edge runtime.

"Unauthorized" / 401 ao rodar comandos da CLI

Sessão expirou. Renove:

supabase login

O reset total — último recurso

O estado local ficou impossível de consertar (containers travados, volumes corrompidos, configuração perdida). Apaga tudo e começa do zero: 

supabase stop --no-backup
docker volume prune -f
supabase start
npm run db:reset
Atenção

--no-backup e volume prune apagam todos os dados locais. Use só quando nada mais funciona. As chaves do supabase status serão regeneradas depois — copie pro .env.

Quando perguntar (e onde)

Se você ficou empacado por mais de 30 minutos em algo que parece infraestrutura, pergunte. Errar de ambiente ou perder dado por tentar consertar do jeito errado custa muito mais do que dois minutos de outra pessoa.

  • Pergunte no canal do time antes de rodar comandos com --force ou prune
  • Se o erro tem stack trace, cole ele inteiro — a primeira linha geralmente esconde a causa real, que está embaixo
  • "Funciona pra mim" dos outros é um bom sinal de que é configuração local sua — foque em .env, versão do Node, status do Docker