Solução de problemas

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.

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.

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.

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.

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.

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.

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.

O nó Renderização 3D Pro responde 503 SCENE_CAPABILITY_UNAVAILABLE. O Renderização 3D Pro (3D Render Pro) 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) e o Renderizar vídeo (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).

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.

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.

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.

Obter ajuda

Se você ainda não conseguir resolver, abra uma issue no GitHub com os logs do Docker do contêiner do app.