Problemas de CLI
Resolva falhas de login na CLI, erros de deploy, falhas do servidor de desenvolvimento e outros problemas de linha de comando. Pesquisável pela mensagem de erro, com soluções passo a passo.
Encontre o erro da sua CLI em uma das seções abaixo.
Problemas de autenticação
Suas credenciais armazenadas estão ausentes ou o refresh token não é mais válido.
Solução: Execute jamdesk login para iniciar uma nova sessão. Isso substitui o que estiver em ~/.jamdeskrc.
Se o erro continuar aparecendo logo após o login, verifique se ~/.jamdeskrc foi gravado:
cat ~/.jamdeskrcO arquivo deve conter um objeto auth com refreshToken, email e uid. Se estiver vazio ou ausente, seu diretório home pode ter problemas de permissão.
A CLI inicia um servidor local na porta 9876 para receber o callback de autenticação do seu navegador. O login expira se o callback não chegar em 2 minutos.
Causas comuns:
- Um firewall está bloqueando o servidor local
- A aba do navegador foi fechada antes de concluir a autenticação
- A porta 9876 está em uso (a CLI escolhe automaticamente outra porta, mas a URL precisa corresponder)
Solução: Copie a URL exibida no terminal e abra-a manualmente. Verifique se o número da porta na URL corresponde ao que a CLI está escutando.
É normal em ambientes sem interface gráfica (sessões SSH, contêineres Docker, runners de CI). A CLI sempre exibe a URL de login no terminal.
Copie-a e abra em qualquer navegador que consiga acessar sua máquina na porta de callback.
Alterar sua senha do Jamdesk invalida todos os refresh tokens existentes. A CLI detecta isso (TOKEN_EXPIRED ou INVALID_REFRESH_TOKEN) e limpa automaticamente a autenticação armazenada.
Execute jamdesk login novamente.
Erros de deploy
Apenas uma build é executada por vez em cada projeto. A CLI retorna esse erro (código BUILD_IN_PROGRESS) quando uma build está na fila ou em execução.
Solução: Aguarde a build atual terminar. Verifique Deployments no dashboard para ver o status. Se uma build parecer travada, peça ao proprietário do projeto que verifique o dashboard.
Não há docs.json no diretório atual, ou ele contém erros de sintaxe JSON.
Solução:
- Certifique-se de estar no diretório correto:
ls docs.json - Execute
jamdesk validatepara ver detalhes específicos do erro - Verifique vírgulas ausentes, colchetes não fechados ou vírgulas finais (a CLI usa JSON, não JSON5, para o docs.json)
Seu tarball compactado excede o limite de 100 MB. Tudo o que não for excluído pelo .gitignore ou pela lista de exclusão embutida é empacotado.
Solução: Verifique o que está sendo incluído. Causas comuns: arquivos de vídeo, PDFs grandes, imagens não comprimidas, dumps de dados. Adicione-os ao .gitignore.
Sempre excluídos, independentemente do .gitignore: .git, node_modules, .next, .env*, *.pem, *.key, credentials.json, .DS_Store.
Todos os arquivos corresponderam a algum padrão de exclusão.
Solução: Verifique se o seu .gitignore não está excluindo arquivos MDX ou o docs.json.
Ou o projectId no docs.json não corresponde a nenhum projeto da sua conta, ou você não é membro desse projeto.
Solução:
- Remova o campo
projectIddodocs.jsone executejamdesk deploynovamente para escolher um novo projeto - Verifique se você está logado com a conta correta:
jamdesk whoami - Confirme a participação no projeto no dashboard
A CLI consulta o status da build a cada 2 segundos. Ela desiste após 3 falhas consecutivas de consulta.
Solução: Pressione Ctrl+C. A build continua em segundo plano. Verifique o status no dashboard. A CLI exibe um link quando você sai.
O upload foi concluído. A build falhou. O terminal mostra o erro do serviço de build.
Solução: Verifique o log da build no dashboard em Deployments. Causas comuns: erros de sintaxe MDX, páginas ausentes referenciadas na navegação, especificações OpenAPI inválidas. Execute jamdesk validate localmente para detectar esses problemas antes do deploy.
A CLI avisa sobre arquivos que parecem conter segredos (.env, *.pem, *.key, credentials.json, arquivos começando com secret). O aviso não bloqueia o deploy.
Solução: Adicione os arquivos ao .gitignore para excluí-los dos uploads. Se forem intencionais (por exemplo, arquivos de chave de exemplo na sua documentação), ignore o aviso.
Problemas do servidor de desenvolvimento
Tente nesta ordem:
jamdesk doctorpara verificar a versão do Node.js (22.18+ ou 24.11+ necessária) e o ambientejamdesk cleanpara limpar as dependências em cachejamdesk dev --verbosepara uma saída detalhada de errosjamdesk dev --cleanpara limpar o cache de build antes de iniciar
O jamdesk para com "jamdesk requires Node.js 22.18+ or 24.11+" em qualquer outra versão, incluindo o Node.js 23. Atualize primeiro o Node.js e depois a CLI.
O jamdesk dev executa a pré-visualização a partir de ~/.jamdesk com o node que aparecer primeiro no seu PATH. Se um gerenciador de versões como Volta, asdf ou mise fixar uma versão mais nova do Node.js apenas para a pasta do seu projeto, a pré-visualização continua rodando no Node.js padrão. O jamdesk doctor informa "first on PATH, used by jamdesk dev", e o jamdesk dev avisa "The node first on your PATH is …".
Solução: Instale uma versão compatível do Node.js e defina-a como padrão, não apenas para o seu projeto. Com o nvm, execute nvm install 24 e depois nvm alias default 24 (no Windows com nvm-windows, nvm install 24 e depois nvm use 24). Abra um novo terminal na sua pasta home e confirme que node --version mostra 22.18+ ou 24.11+.
A CLI tenta 10 portas consecutivas a partir da porta solicitada (padrão 3000). Se todas estiverem ocupadas, a operação falha.
Solução:
# Find what's using the port
lsof -i :3000
# Pick a different port
jamdesk dev --port 3001Defina um padrão permanente adicionando "defaultPort": 3001 ao seu arquivo ~/.jamdeskrc. Não sobrescreva o arquivo, pois ele pode conter suas credenciais de autenticação.
Encerrar o servidor de desenvolvimento no meio da compilação (force quit, falha do sistema) pode corromper o cache .next. A próxima inicialização exibe erros de "corrupted database" ou panic.
Solução:
jamdesk dev --cleanIsso apaga o diretório .next e inicia do zero.
O primeiro jamdesk dev instala as dependências de runtime em ~/.jamdesk/node_modules. Isso acontece uma vez e pode levar de 1 a 2 minutos em conexões mais lentas.
As execuções seguintes pulam a instalação, a menos que a versão da CLI mude.
O npm install na primeira execução expira após 5 minutos.
Solução:
- Verifique sua conexão com a internet
- Execute
jamdesk cleanpara limpar instalações parciais - Tente novamente
- Se o npm estiver consistentemente lento, verifique a configuração do registro npm:
npm config get registry
Validação e verificação de links
O MDX trata < como abertura de tag JSX. Escrever <50% causa um erro de parse.
Solução: Escape com < ou reescreva o trecho. Execute jamdesk validate para ver números de linha e sugestões.
O jamdesk broken-links encontrou links internos apontando para páginas que não existem.
Solução: Verifique os caminhos dos arquivos. Erros comuns: maiúsculas/minúsculas incorretas (Quickstart em vez de quickstart), inclusão da extensão .mdx, ou caminhos antigos que foram renomeados.
A CLI sugere correções para correspondências próximas (a até 3 caracteres de um erro de digitação).
Corrija automaticamente. Se um link quebrado tiver um destino correto e inequívoco (uma âncora com erro de digitação ou desvio de âncora entre idiomas), execute jamdesk fix --dry-run para visualizar as alterações e depois jamdesk fix para aplicá-las. Ele só reescreve links cuja âncora corrigida corresponda a um título real na página de destino. Corrija os casos ambíguos manualmente. Veja Corrigir links quebrados automaticamente.
A CLI valida as especificações OpenAPI referenciadas no docs.json. As falhas incluem referências $ref inválidas, campos obrigatórios ausentes ou erros de sintaxe.
Solução: Execute jamdesk openapi-check caminho/para/spec.yaml para uma saída detalhada. Use o Swagger Editor para depurar especificações complexas.
Problemas gerais
Não instalado globalmente, ou seu shell não consegue localizar o binário.
Solução:
npm install -g jamdeskSe você instalou com curl, certifique-se de que ~/.jamdesk/bin está no seu PATH.
A CLI precisa de acesso de escrita a ~/.jamdesk (cache) e ~/.jamdeskrc (credenciais).
Solução:
ls -la ~/.jamdesk ~/.jamdeskrc
sudo chown -R $(whoami) ~/.jamdesk ~/.jamdeskrcO jamdesk update executa npm install -g jamdesk@latest. Ele falha quando o npm tem problemas de permissão ou o registro está inacessível.
Solução: Atualize manualmente:
npm install -g jamdesk@latestSe isso também falhar, verifique npm config get registry e tente sudo npm install -g jamdesk@latest.
