Desenvolvimento local
| Sintoma |
Verificação |
Correção |
LOCAL_RUNTIME_ENV_INVALID |
NODE_ENV |
use development |
| Bind proibido |
HOST, server.host do Vite |
use 127.0.0.1 |
| Bootstrap inválido |
URL antiga ou reutilizada |
reinicie npm run dev e use a nova URL |
| 401 local |
cookie apagado/expirado |
abra a URL de bootstrap atual |
LOCAL_SESSION_EXPIRED no startup |
prazo de 30 dias encerrado |
exclua os dados locais para iniciar novo período |
| Seed invalida o navegador |
código errado no script |
use somente o código Automação/seed |
| 403 CSRF |
frontend fora da mesma origem |
use /api pelo proxy do Vite |
| Docs desatualizadas |
versão/hash |
npm run ooncore:docs |
| Perfil ausente no banner |
central.app.json → rbac.roles |
declare o papel e reinicie |
LOCAL_OPERATION_NOT_SUPPORTED |
recurso exclusivo da plataforma |
use dublê ou homologue publicado |
| Mongo indisponível |
MONGO_URI, replica set |
inicie o Mongo local |
| Porta ocupada |
4000/5173 |
encerre o processo conflitante |
Backend
| Sintoma |
Causa provável |
OON_ROUTE_REGISTRATION_INVALID |
middleware na posição das opções de router.private |
OON_BACKEND_CWD_INVALID |
start({ cwd }) aponta para fora do backend |
| Boot interrompido por model duplicada |
mesma model em central.domain.json e src/models |
OON_DOMAIN_MANIFEST_INVALID |
ciclo em computed, campo inexistente, tipo inválido — veja issues[] |
| Lista de issues no boot |
central.app.json inválido (compatibility, rbac…) |
| Invariante não funciona |
MongoDB sem replica set |
DATABASE_POOL_BUSY / DATABASE_OPERATION_TIMEOUT |
consultas caras ou concorrência — veja Contenção do MongoDB |
Frontend
| Sintoma |
Causa provável |
Rota reservada pelo OonCore |
declarou /login, /ativacao etc. |
guards obrigatórios … não podem ser desabilitados |
enableRouteGuard: false |
| Rota pública redireciona para login/ativação |
rota privada no índice / (ex.: /usuarios-acessos) ou auth.loginUrl redirecionando visitantes sem sessão |
| App abre o Meus Apps em vez do próprio login |
versão anterior à 0.7.37 usando api.meusAppsUrl como login — atualize o Core |
Chamada vai para /api/api/... |
prefixo /api duplicado na chamada |
| 404 em HTML |
rota não registrada, módulo fora de src/routes ou processo não reiniciado |
Publicação
| Sintoma |
Causa provável |
IMAGE_MODULE_NOT_FOUND |
import de arquivo fora de backend/ ou dependência só em devDependencies |
| Publicação rejeitada |
oon.deploy.json inválido ou declaração de capability incompatível |
| Readiness não passa |
banco inacessível ou boot falhando — confira /api/health/ready |
core.secrets V1 exige single_tenant dedicado |
capability declarada em App multi-tenant |
Ao abrir um chamado, registre método, caminho, status, code e requestId — nunca cole segredos no diagnóstico.