Solución de problemas de builds
Soluciona los fallos de build más comunes identificando mensajes de error con sus causas y soluciones. Cubre errores de configuración, dependencias faltantes, sintaxis MDX y problemas con iconos.
Cuando un build falla, revisa el mensaje de error en el log del build y encuentra la sección correspondiente a continuación.
Ver detalles del error
- Ve a la pestaña Deployments de tu proyecto
- Haz clic en el build fallido
- Revisa el mensaje de error y el log del build
El log muestra exactamente dónde y por qué falló el build.
Errores comunes
Errores de configuración
"Invalid docs.json" — Tu archivo de configuración tiene errores de sintaxis.
Busca comas, corchetes o comillas faltantes.
Ejecuta jamdesk validate para ver los errores detallados.
Corrige los errores y haz push para activar un nuevo build.
Páginas faltantes
"Page not found" — Una página de tu navegación no existe.
- Verifica que el nombre del archivo coincida con la ruta en
docs.json - Las rutas distinguen entre mayúsculas y minúsculas
- No incluyas la extensión
.mdx
Errores de sintaxis MDX
"MDX compilation failed" — Sintaxis MDX o JSX no válida.
Causas comunes:
- Etiquetas sin cerrar (
<Card>sin</Card>) - Caracteres especiales sin escapar (
{en lugar de\{) - Sintaxis de props no válida
Timeout del build
"Build exceeded time limit" — El build tardó demasiado.
Prueba:
- Optimizar imágenes grandes
- Dividir páginas muy extensas
- Reducir el número total de páginas
Pasos de depuración
El log muestra la línea y el archivo exactos que causan el error. Empieza por ahí.
Ejecuta jamdesk dev localmente para reproducir y depurar el problema.
Ejecuta jamdesk validate para verificar tu docs.json y jamdesk broken-links para detectar enlaces internos rotos.
Revisa tu último commit. ¿Añadiste una nueva página? ¿Cambiaste la configuración?
¿Sigues sin resolverlo?
Si no puedes resolver el problema:
- Copia el log completo del build
- Anota el ID de tu proyecto (en la URL)
- Contacta con soporte