Troubleshooting

Problemas comuns e como resolvê-los.

Build

Build falhou (exit code 1)

O build do seu app falhou. Verifique os logs:

veloz logs --build

Causas comuns:

• Dependência faltando — Verifique se todas as dependências estão no package.json (não só instaladas localmente)
• Variável de ambiente no build — Se o build usa variáveis de ambiente (ex: NEXT_PUBLIC_API_URL), defina-as antes do deploy:

veloz env set NEXT_PUBLIC_API_URL=https://api.meuapp.com

• TypeScript com erros — Corrija os erros de tipo. Rode npm run build localmente para verificar

"Node.js version not supported"

Prisma only supports Node.js versions 20.19+, 22.12+, 24.0+.
Please upgrade your Node.js version.

Algumas dependências exigem uma versão específica do Node.js. Configure no veloz.json:

"build": {
  "nodeVersion": "22"
}

Versões disponíveis: "18", "20", "22". O padrão é "22".

"Unable to locate package"

E: Unable to locate package nome-do-pacote

O pacote especificado em aptPackages não existe nos repositórios Ubuntu. Verifique:

• O nome está correto? Use packages.ubuntu.com para buscar
• Pacotes -dev precisam do sufixo completo (ex: libvips-dev, não libvips)
• Nomes são sempre minúsculos (ex: ffmpeg, não FFmpeg)

"Nome de pacote inválido"

O aptPackages aceita apenas nomes válidos de pacotes Debian: letras minúsculas, números, ., + e -. Mínimo 2 caracteres.

// ✅ Correto
"aptPackages": ["ffmpeg", "libvips-dev", "g++"]
 
// ❌ Inválido — caracteres não permitidos
"aptPackages": ["FFmpeg", "my package", "pkg=1.0"]

Build timeout (10 minutos)

O build tem um limite de 10 minutos. Se estourar:

• Otimize dependências — Remova pacotes não usados
• Cache de build — A Veloz reutiliza cache entre deploys. O segundo build costuma ser mais rápido
• Divida o projeto — Se tem um monorepo pesado, considere fazer deploy de apps separadamente

"Diretório raiz não encontrado"

Error: Service root directory 'apps/web' not found

O root no veloz.json aponta para um diretório que não existe. Verifique o caminho:

# Corrija no veloz.json
"root": "apps/web"  # deve corresponder à estrutura real

Runtime

App não responde (502/503)

Seu app está deployado mas retorna erro. Verifique:

1. Logs de runtime:

veloz logs

2. A porta está correta? — A Veloz espera que seu app escute na porta configurada (padrão: 3000):

# Verificar porta configurada
veloz config show
 
# Alterar porta
veloz config set --port 8080

3. O app está escutando em 0.0.0.0? — Não use localhost ou 127.0.0.1. O app precisa escutar em todas as interfaces:

// ❌ Errado
app.listen(3000, "localhost");
 
// ✅ Correto
app.listen(3000, "0.0.0.0");

// Next.js — funciona por padrão
// Express
app.listen(process.env.PORT || 3000, "0.0.0.0");

4. Health check falhando — A Veloz faz health check na rota / por padrão. Se seu app não responde nessa rota, configure um endpoint diferente:

"runtime": {
  "healthCheck": {
    "path": "/health",
    "interval": 30,
    "timeout": 10
  }
}

App reiniciando em loop

O app está crashando e a Veloz tenta reiniciar automaticamente. Verifique os logs:

veloz logs --follow

Causas comuns:

• Variável de ambiente faltando — O app crasha porque uma env var obrigatória não está definida
• Banco de dados inacessível — Verifique a DATABASE_URL e se o banco aceita conexões externas
• Memória insuficiente — Aumente o limite de memória:

veloz config set --memory 1Gi

Erro de memória (OOMKilled)

O app excedeu o limite de memória e foi encerrado:

# Ver limite atual
veloz config show
 
# Aumentar memória
veloz config set --memory 1Gi

Opções disponíveis: 256Mi, 512Mi, 1Gi, 2Gi

Domínios

SSL não provisionado

Certificados SSL são provisionados automaticamente via Let's Encrypt. Se não funcionar:

• DNS propagou? — Após adicionar o domínio, aguarde até 48h para propagação DNS
• Registro CNAME correto? — Verifique se o CNAME aponta para o endereço correto:

veloz domains

• CAA record bloqueando? — Se seu DNS tem registros CAA, adicione Let's Encrypt:

CAA 0 issue "letsencrypt.org"

Domínio não resolve

# Verificar DNS
dig meudominio.com
 
# Deve apontar para o CNAME da Veloz
dig meudominio.com CNAME

CLI

"Você não está autenticado"

Error: Você não está autenticado. Execute `veloz login` primeiro.

veloz login

Se o problema persistir, limpe a sessão e tente novamente:

veloz logout
veloz login

Comando não encontrado

# Verificar instalação
which veloz
 
# Reinstalar
npm install -g onveloz

Upload lento

Para projetos grandes, o upload pode demorar. A CLI envia apenas os arquivos necessários (exclui node_modules, .git, etc.).

Se ainda estiver lento:

• Adicione um .velozignore na raiz (mesma sintaxe do .gitignore):

# .velozignore
data/
*.sql
*.zip

Limites

Ainda com problemas?

• Verifique o status da plataforma: status.onveloz.com
• Entre em contato: support@onveloz.com

Próximos passos

• Logs — Verificar logs de build e runtime
• Configuração — Ajustar build e runtime
• veloz.json — Referência de configuração