Solución de Problemas de Build
Corrige errores comunes de build identificando mensajes de error, causas y soluciones. Abarca errores de configuración, dependencias, sintaxis MDX e iconos.
Cuando un build falla, el log del build te indica qué salió mal y dónde. Encuentra tu mensaje de error a continuación y ve directamente a la solución.
Ver Detalles del Error
- Abre la pestaña Deployments de tu proyecto
- Haz clic en el build fallido
- Lee el mensaje de error y desplázate por el log del build
El log apunta al archivo y la línea exactos que detuvieron el build.
Errores Comunes
Errores de Configuración
Invalid docs.json significa que tu archivo de configuración no puede analizarse. La causa casi siempre es pequeña: una coma extra, un corchete sin cerrar o una comilla faltante.
Busca comas, corchetes o comillas faltantes.
Ejecuta jamdesk validate para ver los errores exactos.
Corrígelos y haz push para activar un nuevo build.
Páginas Faltantes
Un error Page not found se produce cuando tu navegación apunta a un archivo que no existe. Verifica que el nombre del archivo coincida con la ruta en docs.json, que las mayúsculas y minúsculas sean exactas, y que hayas omitido la extensión .mdx.
Errores de Sintaxis MDX
MDX compilation failed apunta a MDX o JSX mal formado en una página. Generalmente es una etiqueta sin cerrar (un <Card> sin su </Card> correspondiente), un carácter sin escapar como un { literal donde querías \{, o una sintaxis de prop no válida.
Tiempo de Build Agotado
Build exceeded time limit es exactamente lo que dice: el build superó el tiempo permitido. Las imágenes grandes y sin optimizar son la causa habitual. Comprime las imágenes, divide las páginas que hayan crecido demasiado y elimina las páginas que ya no publicas.
Advertencias de Build
Las advertencias nunca hacen fallar un build; tu sitio se publica de todas formas. Señalan problemas que vale la pena corregir y aparecen en tres lugares: el correo de advertencias del build, la entrada del build en la pestaña Deployments, y tu terminal cuando ejecutas jamdesk validate o jamdesk dev.
Imágenes Faltantes
Image not found advierte que una página hace referencia a una imagen que tu proyecto no contiene.
Jamdesk verifica cada referencia de imagen (Markdown  y el atributo src en las etiquetas <img loading="lazy"> e <Image>) contra los archivos de tu repositorio. Cuando el archivo de destino no existe, la advertencia te indica la página, el número de línea y la ruta que no pudo resolver, para que una imagen rota nunca se publique como un 404 silencioso.
Para corregirlo, sube la imagen o redirige la ruta a un archivo existente. Las rutas distinguen entre mayúsculas y minúsculas y se resuelven desde la raíz de tu proyecto (con / inicial) o relativas a la página. Una referencia a photo.png sigue funcionando después de que la optimización de imágenes la convierta a WebP.
Las referencias a URL externas, URIs data: y la sintaxis de imágenes dentro de bloques de código se omiten, por lo que los ejemplos en tu propia documentación nunca generan una advertencia falsa.
Pasos de depuración
El log indica el archivo y la línea exactos detrás del error. Empieza por ahí.
Ejecuta jamdesk dev para reproducir el fallo en tu propia máquina.
Ejecuta jamdesk validate para revisar tu docs.json, luego jamdesk broken-links para detectar enlaces internos rotos.
Mira tu último commit. ¿Agregaste una página o cambiaste la configuración?
¿Sigues atascado?
Si nada de lo anterior lo resuelve:
- Copia el log completo del build
- Anota el ID de tu proyecto (está en la URL)
- Contacta al soporte