# Solução de problemas

> Resolva problemas do Nodaro self-hosted a partir de /setup: sintomas e correções de inicialização, portas, CORS, migrações, armazenamento, filas e chaves.

Source: https://nodaro.ai/pt-BR/docs/self-hosting/troubleshooting

Esta página lista os problemas mais comuns de um Nodaro self-hosted, cada um com o **sintoma** e a **correção**. Comece pela página `/setup`, que mostra a maioria deles de relance.

## Começar por /setup
As instalações self-hosted servem uma tela de integridade em tempo real em `http://<your-host>/setup`. Ela não exige login e só mostra se cada parte está presente e funcionando, nunca um segredo.

- **Cartões** verdes ou vermelhos para o banco de dados, o Redis, o armazenamento, a chave de criptografia e as chaves de provedor. O cartão do banco de dados tem um estado próprio, **migrações ausentes**.
- **Uma dica** em cada cartão com falha, com as variáveis a verificar.
- **Atualizações em tempo real**: a página verifica de novo a cada 5 segundos.

Quando a página mostra **API inacessível**, o servidor web está no ar, mas a API não está respondendo. Leia os logs do contêiner com `docker compose -f docker-compose.community.yml logs -f` e verifique se nada bloqueia a porta `3000`.

## A instalação não inicia
**`Missing or invalid env vars` na inicialização.**
A mensagem lista as variáveis que falharam na validação. As causas comuns são uma `SUPABASE_SERVICE_ROLE_KEY` vazia e um `INTERNAL_ORCHESTRATOR_SECRET` com menos de 32 caracteres.

**`port is already allocated` no `docker compose up`.**
A stack só publica duas portas do host: a `3000`, para o app, e a `9001`, para o console do MinIO, esta só no loopback. O Redis e o banco de dados nunca usam uma porta do host. Mude o lado do host do mapeamento em conflito no `docker-compose.community.yml`, por exemplo `"3001:3000"`. Para a porta do app, defina também `PUBLIC_URL` de acordo.

**As migrações falharam na inicialização.**
O log do app indica o arquivo exato. A API se recusa a iniciar com um banco de dados migrado pela metade. Corrija a causa e rode `docker compose -f docker-compose.community.yml up` de novo: os arquivos já aplicados são pulados.

**`password authentication failed for user "supabase_auth_admin"` nos logs do serviço de login.**
O volume `db-data` é mais antigo que a configuração das roles do banco de dados, ou você mudou a `POSTGRES_PASSWORD` depois da primeira inicialização. As senhas das roles só acompanham a `POSTGRES_PASSWORD` na primeira inicialização. Apague o volume com `docker compose -f docker-compose.community.yml down -v`, o que **apaga os seus dados**, ou altere as senhas das roles manualmente como `supabase_admin`.

**A build do Docker não consegue baixar ou verificar o arquivo do ffmpeg.**
Isso só afeta você quando compila a imagem por conta própria. O Dockerfile fixa uma build estática exata do ffmpeg por arquitetura, com `ARG FFMPEG_TARBALL_URL_*` e `ARG FFMPEG_TARBALL_SHA256_*`, porque o áudio e o vídeo renderizados mudam entre as versões do ffmpeg. Um download que falha ou um checksum que não confere interrompe a build, em vez de mudar a sua saída em silêncio. Escolha uma versão datada mais nova das mesmas builds (`BtbN/FFmpeg-Builds` no GitHub) e atualize **tanto** a URL **quanto** o SHA-256 para **as duas** arquiteturas. Trate isso como uma atualização real do ffmpeg e confira a saída renderizada depois.

## O navegador mostra erros
**O editor é renderizado, mas fica em branco ou mostra “Carregando…” para sempre.**
Abra o console do navegador.

- **Erros de CORS:** veja o próximo item.
- **Erros de login:** abra `/config.js` na sua instalação. Ele precisa indicar uma URL do Supabase que o seu navegador consiga acessar, `PUBLIC_URL/supabase` na stack incluída, e a chave anon. O contêiner grava esse arquivo na inicialização a partir de `PUBLIC_URL`, `FRONTEND_SUPABASE_URL` e `SUPABASE_ANON_KEY`: corrija essas variáveis e reinicie.

**Erros de CORS no navegador.**
`http://localhost:3000` e `PUBLIC_URL` são sempre permitidos, então você abriu o app em outra origem, como um endereço da LAN ou outra porta. Defina `PUBLIC_URL` com essa origem, ou liste as origens extras, separadas por vírgula, em `CORS_ORIGIN`, por exemplo `CORS_ORIGIN=http://192.168.1.20:3000`. Depois, rode `docker compose -f docker-compose.community.yml up -d`.

**A ação Editar no NodarCut, ou Editar em um resultado de vídeo de um app, mostra um painel em vez do editor.**
O editor de vídeo hospedado só aceita ser incorporado a partir de `http://localhost:3000`. Em outra origem, rode o seu próprio editor e defina `FREECUT_URL`. Veja [Editores de vídeo e de áudio](https://nodaro.ai/docs/self-hosting/configuration#video-and-audio-editors).

**A ação Editar, em um resultado de áudio, não faz nada ou mostra um painel em vez do editor.**
Não existe um editor de áudio hospedado. Rode o seu próprio AudioMass e defina `AUDIOMASS_URL`.

## Banco de dados
**Uma migração falha com “relation … does not exist”.**
Uma migração rodou fora de ordem. Aplique os arquivos de `supabase/migrations/` na ordem dos nomes, por exemplo no SQL editor do Supabase. Cada um pode rodar de novo em um banco de dados em que já foi aplicado.

**Um callback OAuth retorna `500`.**
As tabelas dos apps OAuth estão faltando porque uma migração não foi aplicada. Aplique todas as migrações na ordem dos nomes dos arquivos. Veja [Banco de dados](https://nodaro.ai/docs/self-hosting/database#apply-the-migrations-to-a-managed-project).

**A API reinicia em loop.**
Ela não consegue acessar o Postgres. Isso é esperado enquanto o banco de dados está fora do ar. Quando o Postgres voltar, rode `docker compose -f docker-compose.community.yml restart nodaro`.

## Armazenamento
**Os uploads falham na stack incluída.**
Abra o console do MinIO em `http://localhost:9001`. As credenciais padrão estão no arquivo do Compose.

**Os uploads para o Cloudflare R2 respondem `401` ou `403`.**
Verifique se o token de API tem a permissão **Object Read & Write** no bucket. Com um domínio personalizado na frente do R2, verifique também a configuração de acesso público do bucket: o Nodaro entrega ao navegador URLs públicas de mídia, então as leituras precisam funcionar sem autenticação.

**Toda requisição ao armazenamento falha com um erro de autorização ou de endpoint.**
Defina `R2_REGION` como a região do armazenamento. A AWS, o DigitalOcean Spaces e um Supabase local rejeitam o padrão `auto`, e o erro deles não menciona a região.

**Todo upload falha depois que você define `STORAGE_OBJECT_ACL`.**
As chaves do armazenamento não têm permissão para definir ACLs de objeto. Deixe a variável vazia, a menos que o seu armazenamento recuse uma política de bucket.

**`[storage] failed to create bucket` no log de inicialização com o R2.**
Inofensivo. Os tokens do R2 não podem criar buckets, e o seu já existe.

## Execuções e nós
**Os workflows entram na fila, mas nunca começam.**
Leia os logs com `docker compose -f docker-compose.community.yml logs nodaro`. O orquestrador pega o trabalho dele no Redis, então nada é executado quando o Redis não pode ser acessado. Verifique `REDIS_URL` e rode `docker compose -f docker-compose.community.yml exec redis redis-cli ping`, que deve responder `PONG`.

**Um nó falha com `Missing API key`.**
O nó chama um provedor que não tem chave. Adicione a chave em `/setup` ou no `.env`. Veja [Chaves de provedor](https://nodaro.ai/docs/self-hosting/provider-keys).

**Imagens e vídeos funcionam, mas todos os recursos de texto falham.**
`KIE_API_BASE_URL` aponta para um proxy que só encaminha os caminhos de mídia. Veja [Passar o tráfego dos provedores pelo seu próprio proxy](https://nodaro.ai/docs/self-hosting/provider-keys#send-provider-traffic-through-your-own-proxy).

**Colar uma chave ou conectar ao Nodaro Cloud falha com `EncryptionKeyMissingError`.**
A instalação não tem uma chave de criptografia. Com um projeto gerenciado no Supabase, defina `NODARO_ENCRYPTION_KEY`, com 64 caracteres hexadecimais gerados por `openssl rand -hex 32`.

**As chaves de provedor aparecem como `missing` (ausente) depois de uma restauração.**
O banco de dados foi restaurado sem a chave de criptografia correspondente. Veja [Backup e restauração](https://nodaro.ai/docs/self-hosting/backups#troubleshooting).

**Um nó falha com `503 nodaro_connection_required`.**
Ele é um nó exclusivo do Nodaro, que precisa de uma conexão com o Nodaro Cloud. Veja [Conectar ao Nodaro Cloud](https://nodaro.ai/docs/self-hosting/cloud-connect).

**As execuções na nuvem falham com `Token expired`.**
O token de 90 dias da conexão expirou. Clique em **Desconectar** e depois em **Conectar**.

**As execuções na nuvem falham com `402 instance_cap_reached`.**
A instalação atingiu o limite de gastos mensal dela. Aumente o limite no app.nodaro.ai, em **Cobrança › Instâncias conectadas**.

**Execuções saudáveis são marcadas como `Execution orphaned`.**
Duas instalações compartilham um banco de dados, com instâncias separadas do Redis. Dê a cada instalação um `RUNTIME_ENV` próprio. Veja [Escalonamento](https://nodaro.ai/docs/self-hosting/scaling#two-installs-one-database).

**O nó Renderização 3D Pro responde `503 SCENE_CAPABILITY_UNAVAILABLE`.**
O [**Renderização 3D Pro** (3D Render Pro)](https://nodaro.ai/docs/nodes/video/pro-3d-render) roda em um serviço de build hospedado e não faz parte das edições self-hosted. Ele nunca recorre em silêncio a outro renderizador. Use o [**Gerar cena 3D** (Generate 3D Scene)](https://nodaro.ai/docs/nodes/video/generate-3d-scene) e o [**Renderizar vídeo** (Render Video)](https://nodaro.ai/docs/nodes/video/render-video), que rodam no seu servidor.

## Login e MCP
**As rotas de SSO respondem `404 unknown_provider`.**
Nenhum provedor está configurado. Verifique `EXTERNAL_SSO_PROVIDERS` e, na stack do Compose, adicione essa variável em `environment:` do serviço `nodaro`. Veja [Login único (SSO)](https://nodaro.ai/docs/self-hosting/sso).

**Toda chamada à API responde `403 sso_required`.**
O perfil de superfície só permite SSO, e a conta não foi criada nem vinculada pelo SSO. Veja [Métodos de login](https://nodaro.ai/docs/self-hosting/editions-and-profiles#sign-in-methods).

**Um cliente MCP recebe `405 wrong_mcp_host`.**
O cliente usa o endereço principal do app. Em vez dele, informe ao cliente o endereço do seu host MCP. Veja [MCP](https://nodaro.ai/docs/self-hosting/mcp).

## Atualizações
**O rótulo da versão só mostra a versão embutida, e as notas da versão estão vazias.**
A verificação de atualizações não consegue ler o GitHub. A linha de log `[update-check] … read failed: HTTP 403 (rate limit: 0 of 60 left…)` significa que o seu endereço de saída gastou a cota anônima do GitHub. Defina `NODARO_UPDATE_CHECK_TOKEN`. Veja [Atualização](https://nodaro.ai/docs/self-hosting/updating#which-version-you-run).

## Obter ajuda
Se você ainda não conseguir resolver, abra uma issue no [GitHub](https://github.com/nodaroai/app.nodaro.ai/issues) com os logs do Docker do contêiner do app.

## Frequently asked questions

### Por onde começo quando o meu Nodaro self-hosted apresenta problemas?

Abra /setup na sua instalação. A página mostra cartões verdes ou vermelhos, em tempo real, para o banco de dados, o Redis, o armazenamento, a chave de criptografia e as chaves de provedor, com uma dica em cada cartão com falha, e não exige login.

### O que significa port is already allocated no docker compose up?

Outro programa usa a porta 3000 ou 9001 na sua máquina. Mude o lado do host desse mapeamento no docker-compose.community.yml, por exemplo para "3001:3000", e defina PUBLIC_URL de acordo.

### Por que o editor fica em branco ou mostra Carregando… para sempre?

Abra o console do navegador. Erros de CORS significam que a origem que você abriu não é permitida, então defina PUBLIC_URL ou CORS_ORIGIN. Erros de login significam que o /config.js indica uma URL do Supabase ou uma chave anon que o navegador não consegue usar.

### Por que os meus workflows nunca começam a ser executados?

O orquestrador pega o trabalho dele no Redis. Verifique os logs com docker compose logs nodaro, verifique REDIS_URL e rode docker compose exec redis redis-cli ping, que deve responder PONG.

### Onde consigo ajuda com uma instalação self-hosted?

Abra uma issue em github.com/nodaroai/app.nodaro.ai com os logs do Docker do contêiner do app.