Jamdesk Documentation logo

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 ~/.jamdeskrc

O 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:

  1. Certifique-se de estar no diretório correto: ls docs.json
  2. Execute jamdesk validate para ver detalhes específicos do erro
  3. 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 projectId do docs.json e execute jamdesk deploy novamente 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:

  1. jamdesk doctor para verificar a versão do Node.js (22.18+ ou 24.11+ necessária) e o ambiente
  2. jamdesk clean para limpar as dependências em cache
  3. jamdesk dev --verbose para uma saída detalhada de erros
  4. jamdesk dev --clean para 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 3001

Defina 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 --clean

Isso 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:

  1. Verifique sua conexão com a internet
  2. Execute jamdesk clean para limpar instalações parciais
  3. Tente novamente
  4. Se o npm estiver consistentemente lento, verifique a configuração do registro npm: npm config get registry

O MDX trata < como abertura de tag JSX. Escrever <50% causa um erro de parse.

Solução: Escape com &lt; 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.

Especificações Swagger 2.0 exibem um aviso, mas ainda passam na validação.

Problemas gerais

Não instalado globalmente, ou seu shell não consegue localizar o binário.

Solução:

npm install -g jamdesk

Se 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 ~/.jamdeskrc

O 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@latest

Se isso também falhar, verifique npm config get registry e tente sudo npm install -g jamdesk@latest.

Ainda com problemas?

Visão geral da CLI

Referência completa de comandos

Contatar o suporte

Inclua a saída completa do erro