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 activos.

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 errores detallados
2. Comprueba que no falten comas, corchetes ni 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. Comprueba que el archivo existe en la ruta especificada
2. Verifica que la ruta en docs.json coincida con el nombre real del archivo (sin .mdx)
3. Las rutas distinguen mayúsculas de minúsculas, así que revisa la capitalización

INVALID_FRONTMATTER

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

Causa: El frontmatter YAML al inicio de un archivo MDX está malformado.

Solución:

1. Asegúrate de que el frontmatter empiece y termine con ---
2. Comprueba la sintaxis YAML (dos puntos faltantes, sangría incorrecta)
3. Encierra entre comillas 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 correctamente cerradas (<Card>...</Card>)
2. Comprueba 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 ver los nombres correctos
2. Los componentes distinguen mayúsculas de minúsculas: usa <Card> y no <card>
3. Verifica que no estés importando componentes personalizados (no está soportado)

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 conocer las props válidas
2. Elimina las props no soportadas
3. Asegúrate de que los valores de las props sean del tipo correcto

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. Comprueba 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. Asegúrate de que las referencias externas sean accesibles

Tiempo de espera del build

BUILD_TIMEOUT

Mensaje: "Build exceeded maximum time limit"

Causa: El build tardó más del tiempo permitido (normalmente 5 minutos).

Solución:

1. Optimiza las imágenes grandes (comprime o redimensiona)
2. Divide las páginas muy extensas en páginas más pequeñas
3. Reduce el número de páginas si es extremadamente elevado
4. Contacta con soporte si el problema persiste

Errores de activos

ASSET_NOT_FOUND

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

Causa: Una imagen o archivo referenciado en tu documentación no existe.

Solución:

1. Verifica que el archivo existe en la ruta especificada
2. Comprueba que la ruta sea relativa a tu directorio de documentación
3. Las rutas distinguen mayúsculas de minúsculas, así que revisa el nombre exacto del archivo

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 usando herramientas como TinyPNG o ImageOptim
2. Usa formatos adecuados (WebP para fotos, SVG para iconos)
3. Considera alojar los archivos muy grandes de forma externa

Obtener ayuda

Si no puedes resolver un error:

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

Artículos relacionados