---
title: Referencia de errores de build
description: Cada código de error de build con su causa raíz y solución -- configuración, sintaxis MDX, OpenAPI, tiempos de espera y problemas de activos.
---

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](/es/components/overview) 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](/es/help/faq) problemas habituales
3. [Contacta con soporte](/es/help/support/contact) con el ID de tu proyecto y los detalles del error

## Artículos relacionados

<Columns cols={2}>
  <Card title="Fallos de build" icon="triangle-exclamation" href="/es/help/troubleshooting/build-failures">
    Fallos de build habituales y soluciones
  </Card>
  <Card title="Contactar soporte" icon="headset" href="/es/help/support/contact">
    Obtén ayuda de nuestro equipo
  </Card>
</Columns>