# Troubleshooting

> Sintomas comuns no desenvolvimento local e na publicação, com a verificação e a correção de cada um.

## 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 |

> [!DANGER]
> Nunca resolva erro local adicionando token fixo, `0.0.0.0`, proxy externo ou credencial de Deployment.

## 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](/docs/operacao/banco-de-dados) |

## 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.

Fonte: https://sdk.oonapps.com/docs/operacao/troubleshooting