Solução de problemas
Soluções rápidas para problemas comuns no Jamdesk, incluindo falhas de build, verificação de DNS, conexões com o GitHub e dados de análise ausentes.
Cada seção traz uma solução rápida e um link para o guia completo na Central de ajuda.
Para dúvidas sobre conta, faturamento ou produto que não estão cobertas aqui, consulte a Central de ajuda.
Falhas de build
Seu dashboard mostra um build como "Failed". Causas comuns:
- Uma página MDX com um import ou componente quebrado.
docs.jsoninválido (colchetes não fechados, vírgulas sobrando após o último item de um array).- Uma página listada na navegação do
docs.jsonque não existe como arquivo.mdx.
Execute jamdesk dev antes de fazer push. Ele detecta os dois primeiros problemas localmente.
O log de build no seu dashboard mostra o arquivo e a linha exatos do erro. Comece por ele.
Para códigos de erro específicos, consulte Falhas de build e a Referência de erros.
Domínio personalizado não é verificado
Se seu domínio continua "Pending" depois de você adicionar os registros de DNS, verifique estes itens na ordem:
- Confirme que você adicionou o registro TXT
_jamdesk.<hostname>. O roteamento não é ativado sem ele. Um registro TXT ausente é a causa mais comum de um domínio Pending. O hostname é o domínio completo que você está verificando (paradocs.example.com, o nome do registro TXT é_jamdesk.docs.example.com). - Confirme que você adicionou um registro CNAME (não um registro A) para subdomínios.
- Se você usa a Cloudflare, defina o proxy como DNS only (nuvem cinza) para os dois registros.
- Verifique a propagação em whatsmydns.net.
# Verify the TXT verification record
dig TXT _jamdesk.docs.yourdomain.com
# Verify your CNAME is resolving
dig CNAME docs.yourdomain.com
O dashboard pode exibir "Pending" por até 30 minutos depois que o dig mostra seus registros resolvendo. O verificador fica atrás de resolvedores upstream que armazenam em cache respostas negativas de DNS. Aguarde meia hora antes de procurar um problema mais profundo.
Solução de problemas de DNS cobre particularidades de cada provedor.
A especificação OpenAPI válida falha na validação
O jamdesk dev rejeita uma especificação válida com erros como #/servers/0/variables/host must NOT have unevaluated properties. Isso geralmente acontece com variáveis de servidor que têm um description, ou com uma licença que contém apenas um name. O problema está na cópia do meta-schema OpenAPI 3.1 usada pela CLI. O npm 12 bloqueia, por padrão, os scripts de instalação dos pacotes. Isso pula a etapa que corrige dois defeitos conhecidos no schema.
Atualize a CLI. A versão 1.1.167 e posteriores corrige o schema no momento da validação:
npm install -g jamdesk@latest
Em uma versão antiga fixada, execute npm install -g --allow-scripts=jamdesk jamdesk para permitir que a etapa de instalação seja executada.
Repositório do GitHub não aparece
Um repositório ausente da lista geralmente significa que o app do GitHub da Jamdesk não está instalado na organização do repositório. O acesso ao repositório também pode estar definido como "Selected repositories" sem incluir o seu. Autorize novamente em github.com/settings/installations e conceda acesso a "All repositories" ou ao repositório específico.
Consulte Problemas do GitHub para problemas de webhook e permissões.
Dados de análise ausentes
As análises levam até 24 horas para aparecer após o primeiro deploy de um site. Bloqueadores de anúncios e o Do Not Track impedem que algumas visitas sejam contabilizadas. Seus números sempre estarão atrás dos logs do servidor. Se seu dashboard ainda mostra zero visitantes, confirme que seu site está publicado e acessível publicamente.
Problemas de análise aborda em mais detalhes dados atrasados ou ausentes.
Problemas de login
Se você não consegue entrar ou é redirecionado de volta para a tela de login, limpe o cache e os cookies de dashboard.jamdesk.com. Depois, tente uma janela anônima. O login com GitHub exige que seu e-mail do GitHub corresponda ao e-mail da sua conta Jamdesk.
Consulte Problemas de login para os passos de recuperação de conta.
