Documentação

Solução de problemas

Problemas comuns do Motoko Base e correções — auth, OAuth, banco, email, billing, storage, Sentry e falhas de build.

Correções rápidas para problemas que costumam aparecer na primeira configuração ou no deploy de produção. Para detalhes de env, veja Environment Variables.

A autenticação não funciona

Sintomas: Não consegue entrar, sessão perdida ao atualizar, loops de redirect, cookies não definidos.

Verificação	Correção
`BETTER_AUTH_SECRET` ausente	Defina em `.env` — obrigatório em produção
`BETTER_AUTH_URL` errado	Deve coincidir com a URL que você abre no navegador (incluindo `http://` vs `https://`, porta, sem problemas de barra final)
Descompasso com `NEXT_PUBLIC_APP_URL`	Alinhe ambos à mesma origem em cada ambiente
Banco fora / migrações não rodadas	Verifique `DATABASE_URL`, execute `pnpm db:migrate`
Email não verificado	O dashboard exige verificação — confira a caixa de entrada ou use `/verify-email`

Veja Better Auth e Installation.

Erro de callback OAuth

Sintomas: redirect_uri_mismatch, erro do Google/GitHub após autorizar, botões sociais desabilitados.

Verificação	Correção
Botão desabilitado	Defina ambos `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` (ou o par do GitHub); reinicie o servidor de desenvolvimento
URL de callback divergente	O console do provedor deve ter exatamente `{BETTER_AUTH_URL}/api/auth/callback/google` ou `.../github`
Produção vs local	Adicione URLs de callback separadas para localhost e o domínio de produção
Modo de teste do Google	Adicione sua conta como usuário de teste na tela de consentimento OAuth

Veja OAuth Setup.

Falha na conexão com o banco

Sintomas: App trava no boot, migrações falham, ECONNREFUSED, erros de timeout.

Verificação	Correção
`DATABASE_URL` ausente ou errado	Copie do dashboard Supabase/host; nunca use `NEXT_PUBLIC_*`
Migrações não aplicadas	`pnpm db:migrate`
Pooler vs direto	Runtime: transaction pooler (muitas vezes porta `6543`). Migrações: tente URL direta (porta `5432`) se o DDL falhar
Projeto Supabase pausado	Restaure o projeto no dashboard do Supabase
`prepare: false`	Já definido em `src/lib/db/index.ts` — obrigatório para o pooler do Supabase; não habilite prepared statements

Veja Database e Migrations.

Emails não estão sendo enviados

Sintomas: Sem email de verificação após o cadastro, forgot-password não faz nada, email de boas-vindas ausente.

Verificação	Correção
Resend não configurado	Defina `RESEND_API_KEY` e `EMAIL_FROM`
Remetente errado	Use domínio verificado em produção; para testes tente `onboarding@resend.dev`
`BETTER_AUTH_URL` errado	Links de reset/verificação apontam para o host errado — corrija a origem
Erro na página de forgot-password	A página checa `isEmailConfigured()` — ambas as vars do Resend são necessárias
Dashboard do Resend	Confira os logs do Resend por bounces ou erros de API

Veja Email (Resend).

O checkout do Polar não abre

Sintomas: Página de billing mostra “not configured”, botão de checkout falha, permanece em Free após o pagamento.

Verificação	Correção
Variáveis de ambiente faltando	`POLAR_ACCESS_TOKEN`, `POLAR_PRO_MONTHLY_PRODUCT_ID`, `POLAR_WEBHOOK_SECRET`
Sandbox vs production	`POLAR_SERVER=sandbox` com token/produto sandbox — ou `production` com credenciais ao vivo
URL do webhook	`{APP_URL}/api/billing/webhooks/polar` — deve ser alcançável pelo Polar
Após o checkout	A página de billing usa `getFreshBillingSummary` no redirect de sucesso; confirme que o webhook foi entregue
Sem cliente Polar	O usuário precisa de um cliente Polar (criado no cadastro quando billing está configurado) antes do portal

Veja Payments (Polar).

Upload R2 falha

Sintomas: Página de storage mostra mensagem de config, erro de URL pré-assinada, falha CORS no upload do navegador, 403 no PUT.

Verificação	Correção
Vars `R2_*` faltando	Defina account ID, access key, secret e nome do bucket
Nome do bucket com barra	`my-bucket/demo` → bucket `my-bucket`, prefix `demo/` — ou use `R2_PREFIX`
CORS	Adicione a origem do app à política CORS do bucket R2 no Cloudflare
Arquivo grande demais / MIME errado	Limites em `src/features/storage/config.ts`
Validação HEAD falha	O servidor valida o upload após o PUT — confira se o objeto existe no dashboard R2

Veja Storage (R2).

O Sentry não recebe erros

Sintomas: Sem issues no dashboard do Sentry após lançar um erro de teste.

Verificação	Correção
Testando em `next dev`	O Sentry fica desativado em dev — use `pnpm build && pnpm start` ou teste na produção implantada
DSN ausente	Defina `NEXT_PUBLIC_SENTRY_DSN`
Projeto errado	Confirme que o DSN corresponde ao projeto Sentry que você está vendo
Bloqueadores de anúncio	O navegador pode bloquear o Sentry — tente a rota `/sentry-tunnel` ou um erro no servidor
Source maps	Defina `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT` em tempo de build para stacks legíveis

Veja Monitoring (Sentry).

Build falha

Sintomas: pnpm build termina com erros localmente ou no CI.

Verificação	Correção
Versão do Node	Requer Node ≥ 22 — rode `node -v`
Erros de tipo	`pnpm typecheck` — corrija os problemas TypeScript reportados
Erros de lint	`pnpm lint`
Env faltando no build	A maioria das vars é só de runtime; vars de upload do Sentry só se usar source maps
MDX / docs	Rode `pnpm install` para que o `postinstall` (`fumadocs-mdx`) conclua
Lockfile	Use `pnpm install` — não misture npm/yarn

pnpm lint && pnpm typecheck && pnpm test && pnpm build

Ainda travado?

Relia Installation e Configuração de produção
Compare seu .env com .env.example
Confira os dashboards das integrações (Resend, Polar, Cloudflare, PostHog, Sentry)
Busque no README do repo e nos READMEs de features em src/lib/email/, src/lib/security/, etc.

Scripts — Referência de comandos.

Referência de configuração — Índice de arquivos de configuração.