Solución de problemas

Empieza aquí cuando algo no funcione. Cada sección incluye una solución rápida y un enlace a la guía más detallada del Centro de ayuda.

Fallos de build

Tu dashboard muestra un build como "Failed". La mayoría de los fallos provienen de una de estas tres causas: una página MDX con una importación o un componente roto, una edición no válida en docs.json (corchetes sin cerrar, comas finales después del último elemento del array) o una página listada en la navegación de docs.json que no existe como archivo .mdx. Las dos primeras se detectan localmente con jamdesk dev antes de llegar a un build desplegado. Ejecutarlo una vez antes de hacer push suele ahorrar una vuelta completa.

Para códigos de error específicos, consulta Fallos de build y la Referencia de errores.

El dominio personalizado no se verifica

¿El dominio se queda en "Pending" después de agregar los registros DNS? Sigue estos pasos en orden:

1. Confirma que agregaste el registro TXT _jamdesk.<hostname>. El enrutamiento no se activa sin él, y la falta del TXT es la causa más común de un dominio en estado Pending. El hostname es el dominio completo que estás verificando (para docs.example.com, el nombre del registro TXT es _jamdesk.docs.example.com).
2. Confirma que agregaste un registro CNAME (no un registro A) para subdominios.
3. Si usas Cloudflare, configura el proxy en DNS only (nube gris) para ambos registros.
4. Verifica la propagación en whatsmydns.net.

# Verify the TXT verification record
dig TXT _jamdesk.docs.yourdomain.com

# Verify your CNAME is resolving
dig CNAME docs.yourdomain.com

Algo no tan obvio que vale la pena saber: incluso después de que dig muestre que tus registros están resolviendo, el dashboard puede seguir mostrando "Pending" hasta por 30 minutos. El verificador está detrás de resolvers upstream que almacenan en caché las respuestas DNS negativas, y esa ventana de caché debe expirar antes de que la nueva verificación tenga éxito. Si todo resuelve localmente pero el dashboard no se ha actualizado, espera media hora antes de asumir que hay un problema más profundo.

Problemas de DNS cubre particularidades específicas de cada proveedor.

Una especificación de OpenAPI válida no pasa la validación

jamdesk dev rechaza una especificación que sabes que es válida, con errores como #/servers/0/variables/host must NOT have unevaluated properties, normalmente en variables de servidor que incluyen una description, o en una licencia que solo tiene name. La especificación está bien: el problema es la copia del meta-esquema de OpenAPI 3.1 que usa el CLI. npm 12 bloquea los scripts de instalación de paquetes de forma predeterminada, lo que omitió el paso que corrige dos defectos conocidos en ese esquema.

Actualiza el CLI: la versión 1.1.167 y posteriores reparan el esquema en el momento de la validación, así que el paso de instalación ya no importa:

npm install -g jamdesk@latest

Si estás fijado a una versión anterior, npm install -g --allow-scripts=jamdesk jamdesk permite que se ejecute el paso de instalación.

El repositorio de GitHub no aparece

Si tu repo no aparece en la lista al crear un proyecto, probablemente la GitHub App de Jamdesk no esté instalada en la organización del repo, o el acceso a repositorios esté configurado en "Selected repositories" sin incluir el tuyo. Vuelve a autorizar en github.com/settings/installations y concede acceso a "All repositories" o al repo específico que necesites.

Consulta Problemas de GitHub para problemas de webhooks y permisos.

Faltan datos de analítica

Hay algunas razones comunes por las que tu dashboard muestra cero visitantes. Los datos de analítica tardan hasta 24 horas en aparecer después del primer despliegue de un sitio, así que los proyectos recién creados se ven vacíos durante un tiempo. Los bloqueadores de anuncios y Do Not Track evitan que se cuente una parte de las visitas, así que tus números siempre irán por detrás de tus logs del servidor. Si ninguno de estos casos aplica, confirma que tu sitio esté realmente desplegado y sea accesible públicamente.

Problemas de analítica profundiza en datos retrasados o faltantes.

Problemas de inicio de sesión

¿No puedes iniciar sesión o te devuelve una y otra vez a la pantalla de inicio de sesión? Borra la caché y las cookies de dashboard.jamdesk.com, y luego prueba con una ventana de incógnito. Si inicias sesión con GitHub, tu correo de GitHub debe coincidir con el correo de tu cuenta de Jamdesk.

Consulta Problemas de inicio de sesión para conocer los pasos de recuperación de cuenta.

¿Sigues atascado?