Referencia de errores de build

Encuentra tu código de error con Ctrl/Cmd+F o navega por categoría: configuración, MDX, OpenAPI, tiempos de espera y assets.

Errores de configuración

INVALID_DOCS_JSON

Mensaje: "Invalid docs.json configuration"

Causa: Tu archivo docs.json tiene errores de sintaxis o valores no válidos.

Solución:

1. Ejecuta jamdesk validate localmente para ver los errores en detalle
2. Revisa si faltan comas, corchetes o comillas
3. Verifica que todos los valores coincidan con el esquema esperado

MISSING_PAGE

Mensaje: "Page 'path/to/page' referenced in navigation but file not found"

Causa: Una página listada en la navegación de docs.json no existe.

Solución:

1. Verifica que el archivo exista en la ruta especificada
2. Comprueba que la ruta en docs.json coincida con el nombre de archivo real (sin .mdx)
3. Las rutas distinguen mayúsculas y minúsculas, así que revisa las mayúsculas

INVALID_FRONTMATTER

Mensaje: "Invalid frontmatter in 'path/to/page'"

Causa: El frontmatter YAML al inicio de un archivo MDX tiene un formato incorrecto.

Solución:

1. Asegúrate de que el frontmatter empiece y termine con ---
2. Revisa si hay sintaxis YAML no válida (faltan dos puntos, indentación incorrecta)
3. Entrecomilla las cadenas que contengan caracteres especiales

Errores de MDX

MDX_SYNTAX_ERROR

Mensaje: "MDX compilation failed"

Causa: Sintaxis MDX o JSX no válida en tu contenido.

Solución:

1. Asegúrate de que todas las etiquetas JSX estén cerradas correctamente (<Card>...</Card>)
2. Verifica que las props usen la sintaxis correcta (title="value" y no title=value)
3. Escapa las llaves en texto normal: \{ en lugar de {

COMPONENT_NOT_FOUND

Mensaje: "Unknown component 'ComponentName'"

Causa: Estás usando un componente que no existe en Jamdesk.

Solución:

1. Consulta la referencia de componentes para conocer los nombres correctos
2. Los componentes distinguen mayúsculas y minúsculas: usa <Card>, no <card>
3. Verifica que no estés importando componentes personalizados (no compatible)

INVALID_PROPS

Mensaje: "Invalid props for component 'ComponentName'"

Causa: Un componente recibió props que no acepta.

Solución:

1. Consulta la documentación del componente para ver las props válidas
2. Elimina cualquier prop no compatible
3. Revisa el tipo esperado de la prop en la documentación del componente (por ejemplo, cols espera un número, no una cadena)

Errores de OpenAPI

OPENAPI_PARSE_ERROR

Mensaje: "Failed to parse OpenAPI specification"

Causa: Tu archivo de especificación OpenAPI tiene sintaxis o estructura no válida.

Solución:

1. Ejecuta jamdesk openapi-check para validar localmente
2. Usa un validador de OpenAPI como Swagger Editor
3. Revisa que la sintaxis JSON o YAML sea válida

OPENAPI_REFERENCE_ERROR

Mensaje: "Unresolved reference in OpenAPI spec"

Causa: Un $ref en tu especificación OpenAPI apunta a una definición que no existe.

Solución:

1. Verifica que todas las rutas $ref sean correctas
2. Comprueba que los esquemas referenciados existan en components/schemas
3. Si un $ref apunta a un archivo externo o una URL, confirma que el archivo esté incluido en tu proyecto y que la URL sea accesible

Tiempo de espera de build

BUILD_TIMEOUT

Mensaje: "Build exceeded maximum time limit"

Causa: El build tardó más del tiempo permitido (por lo general, 5 minutos).

Solución:

1. Optimiza las imágenes grandes (comprímelas o cámbialas de tamaño)
2. Divide las páginas muy grandes en páginas más pequeñas
3. Reduce la cantidad de páginas si son demasiadas
4. Contacta con soporte si el problema persiste

Errores de assets

ASSET_NOT_FOUND

Mensaje: "Asset 'path/to/asset' not found"

Causa: Una imagen o archivo referenciado en tus docs no existe.

Solución:

1. Verifica que el archivo exista en la ruta especificada
2. Comprueba que la ruta sea relativa a tu directorio de docs
3. Las rutas distinguen mayúsculas y minúsculas, así que revisa el nombre del archivo exactamente

ASSET_TOO_LARGE

Mensaje: "Asset exceeds maximum file size"

Causa: Una imagen o archivo supera el límite de 10 MB.

Solución:

1. Comprime las imágenes con herramientas como TinyPNG o ImageOptim
2. Usa formatos adecuados (WebP para fotos, SVG para íconos)
3. Considera alojar los archivos muy grandes de forma externa

Obtener ayuda

Si no puedes resolver un error:

1. Revisa el registro completo del build en tu dashboard para más contexto
2. Busca en las preguntas frecuentes los problemas comunes
3. Contacta con soporte con el ID de tu proyecto y los detalles del error

Artículos relacionados