epubcheck es el validador de conformidad canónico de EPUB, mantenido por el DAISY Consortium y la comunidad del W3C. Lee tu archivo contra la especificación EPUB y reporta cada desviación como un ERROR o un WARNING, cada uno etiquetado con un código corto como RSC-005. Los códigos parecen crípticos, pero casi todos son mecánicos: un archivo que falta, un atributo en el lugar equivocado, o un recurso que no debería estar ahí.
Esta guía recorre las familias de error que realmente te vas a encontrar, qué causa cada una y su arreglo típico. La regla de oro: resuelve primero cada línea de ERROR — los errores rompen la conformidad y pueden impedir que los lectores abran el libro — y luego trabaja las líneas de WARNING. Origami usa el mismo motor de epubcheck, explica cada hallazgo en lenguaje llano y ordena los bloqueantes arriba para que sepas exactamente qué tocar primero.
Errores de esquema: RSC-005
RSC-005 es el error más habitual, y el que más asusta. Significa que un archivo falló la validación de esquema contra la spec — el XML está bien formado, pero algo en él no está permitido donde lo pusiste. Causas frecuentes: un atributo que no corresponde a un elemento, un elemento anidado dentro de otro que no puede contenerlo, un valor fuera de la lista permitida, o una propiedad indebida en un itemref del spine.
El texto después del código es la instrucción real — léelo literalmente. Un mensaje como “attribute X not allowed here” te dice con precisión qué atributo quitar o mover. Los arreglos casi siempre son locales: borra el atributo problemático, reanida el elemento o corrige el valor. Arregla uno, vuelve a ejecutar, y un número sorprendente de líneas RSC-005 suele reducirse a una sola causa repetida entre capítulos.
Recursos que faltan y recursos remotos
RSC-007 y RSC-001 significan que epubcheck siguió una referencia — una hoja de estilos, imagen, fuente o una entrada del spine — y no encontró el destino dentro del contenedor. La causa casi siempre es una discrepancia de ruta o de mayúsculas: un href apunta a images/Cover.jpg pero el archivo es images/cover.jpg, o un archivo se renombró y su referencia no. Las rutas de EPUB distinguen mayúsculas; corrige la ruta o restaura el archivo que falta.
RSC-006 marca un recurso remoto — una URL que apunta fuera del EPUB. La spec solo permite referencias remotas para un conjunto reducido de medios, como audio y video; todo lo demás, incluidas imágenes, fuentes y hojas de estilo, debe ir empaquetado dentro del contenedor. El arreglo es descargar el recurso, añadirlo al manifest y reapuntar la referencia a la copia local.
El documento de paquete: errores OPF
Los errores OPF-* vienen del documento de paquete .opf — el manifest, la metadata y el spine. Los más frecuentes: un archivo que existe en el contenedor pero no está declarado en el manifest (o está declarado pero falta), un spine que referencia un id sin item correspondiente en el manifest, o metadata Dublin Core requerida ausente o mal formada, como un dc:identifier, dc:title o dc:language faltante.
Trata el OPF como la fuente de verdad: cada archivo de contenido debe aparecer una vez en el manifest con el media type correcto, y cada itemref del spine debe apuntar a un id de manifest existente. Añade la declaración que falta, corrige el media type o proporciona el valor de metadata requerido, y la cascada de errores derivados suele resolverse con ello.
Marcado, navegación y empaquetado
Los errores HTM-* significan que el propio XHTML está mal formado o usa algo que la spec no permite — una etiqueta sin cerrar, un namespace no declarado o una construcción obsoleta. Como el contenido EPUB es XHTML, debe ser XML bien formado: cada etiqueta cerrada, cada atributo entre comillas. Los errores de NCX y navegación apuntan a la tabla de contenidos — un enlace roto en el documento nav, o un desajuste entre el nav y el orden del spine.
Los errores PKG-* tienen que ver con cómo se ensambla el ZIP. El clásico: el archivo mimetype debe ser la primera entrada del archivo y estar guardado sin comprimir, sin bytes extra. Si tu herramienta de compresión lo comprimió o reordenó las entradas, epubcheck se queja antes incluso de leer el contenido. Vuelve a empaquetar con el mimetype primero y sin comprimir — la mayoría de las herramientas de exportación EPUB lo hacen solas, así que esto suele significar evitar un re-zip manual.
La solución, paso a paso
-
1
Valida y lee el reporte en crudo
Pasa tu EPUB por epubcheck 5.x y captura la salida completa. Cada línea trae un código, una severidad y una ubicación de archivo y línea — ese trío es tu mapa al punto exacto que hay que cambiar. No adivines; el reporte ya nombra el archivo.
-
2
Ordena por severidad, primero los bloqueantes
Separa los errores de los warnings. Los errores rompen la conformidad y pueden impedir que los lectores abran el libro, así que resuelve cada uno antes de tocar un solo warning. Los warnings son de aviso y pueden esperar a que los errores desaparezcan.
-
3
Arregla por familia, del contenedor hacia adentro
Agrupa los hallazgos — esquema, recursos, documento de paquete, marcado — y empieza por el contenedor: primero mimetype y empaquetado, luego el OPF, y después los archivos de contenido. Arreglar una causa raíz suele resolver varias líneas de golpe.
-
4
Vuelve a validar hasta que el reporte esté limpio
Ejecuta epubcheck de nuevo tras cada tanda de arreglos. Los códigos encadenan, así que una corrección puede resolver o revelar otras. Repite hasta que no quede ningún error, y luego decide qué warnings vale la pena limpiar para tus lectores.
Los códigos de error, uno por uno
Cada bloque de abajo tiene las mismas cinco partes: la línea que epubcheck imprime de verdad, qué significa, por qué pasa, el arreglo y el error con el que más se confunde. Salta directo a un código, o busca en esta página la frase que pegaste de tu reporte.
RSC-005 — Error al parsear el archivo
Lo que imprime epubcheck:
Error while parsing file: %1$s
- Qué significa
- El archivo es XML bien formado, pero rompió una regla del esquema EPUB: algo no está permitido donde lo pusiste. Todo lo que sigue a los dos puntos es el texto del propio validador de esquema, citado tal cual por epubcheck.
- Por qué pasa
- Un atributo que no corresponde a ese elemento, un elemento anidado dentro de otro que no puede contenerlo, un valor fuera de la lista permitida, o una propiedad suelta en un itemref del spine.
- El arreglo
- Lee el mensaje literalmente: nombra el atributo o el elemento culpable. Bórralo, re-anídalo o corrige el valor, y vuelve a validar. Decenas de líneas RSC-005 suelen reducirse a un error de plantilla repetido en todos los capítulos.
- Cuándo no es esto
- Como epubcheck cita acá el texto crudo del validador de esquema, el mensaje que estás mirando puede no traer ningún código propio. Si pegaste una frase de tu reporte y no la encuentras en ninguna parte de esta página, es casi seguro un mensaje de esquema anidado dentro de RSC-005 — empieza por acá y no por buscar un código que no existe.
RSC-007 — No se encontró el recurso referenciado dentro del EPUB
Lo que imprime epubcheck:
Referenced resource "%1$s" could not be found in the EPUB.
- Qué significa
- epubcheck siguió una referencia — una imagen, una hoja de estilos, una fuente, una entrada del spine — y el destino no está dentro del contenedor.
- Por qué pasa
- Casi siempre una diferencia de ruta o de mayúsculas: un href apunta a images/Cover.jpg mientras que el archivo es images/cover.jpg, o se renombró un archivo y no sus referencias.
- El arreglo
- Haz que la referencia coincida exactamente con el nombre y la carpeta reales. Las rutas de EPUB distinguen mayúsculas y se resuelven relativas al archivo que las contiene, no a la raíz del libro. Después, vuelve a validar.
- Cuándo no es esto
- Si el archivo sí está en el contenedor y epubcheck igual se queja, el problema es de declaración y no de ubicación: eso es RSC-008, o el mismo hecho visto desde el paquete, que es OPF-003.
RSC-008 — El recurso referenciado no está declarado en el manifiesto OPF
Lo que imprime epubcheck:
Referenced resource "%1$s" is not declared in the OPF manifest.
- Qué significa
- El archivo existe y la ruta resuelve, pero el documento de paquete nunca lo declara. Para un lector, un recurso no declarado no existe.
- Por qué pasa
- Un recurso agregado a mano después de exportar — una fuente, una imagen de último momento, una hoja de estilos puesta en la carpeta sin que nadie tocara el OPF.
- El arreglo
- Agrega un item al manifiesto con un id único, el href relativo a la carpeta del propio OPF y el media-type correcto. Si el recurso se referencia desde el spine, agrega también el itemref correspondiente.
- Cuándo no es esto
- RSC-007 significa que la referencia no tiene archivo. Esto significa que el archivo no tiene declaración. Se parecen en el reporte y tienen arreglos opuestos.
RSC-001 — No se encontró el archivo
Lo que imprime epubcheck:
File "%1$s" could not be found.
- Qué significa
- Una ruta nombrada en la estructura del paquete no resuelve a nada dentro del contenedor.
- Por qué pasa
- Una entrada que nunca entró al ZIP, o una ruta en META-INF/container.xml o en el OPF que apunta a donde el archivo no está.
- El arreglo
- Verifica que container.xml nombre el .opf real, y luego que cada href del manifiesto resuelva relativo a la carpeta donde vive el OPF. Vuelve a empaquetar cuando las rutas coincidan.
- Cuándo no es esto
- RSC-007 es una referencia rota desde adentro de tu contenido. RSC-001 suele ser una ruta rota en el empaquetado que lo rodea, así que mira el contenedor antes de abrir un capítulo.
RSC-006 — No se permite la referencia a un recurso remoto en este contexto
Lo que imprime epubcheck:
Remote resource reference is not allowed in this context; resource "%1$s" must be located in the EPUB container.
- Qué significa
- Algo que el lector necesita descargar para renderizar la página vive en una URL fuera del libro. La especificación solo permite referencias remotas para un conjunto acotado de medios, como audio y video.
- Por qué pasa
- Una webfont alojada, una imagen que sigue apuntando a un CDN, o un include de hoja de estilos que sobrevivió de una plantilla HTML.
- El arreglo
- Descarga el recurso, agrégalo al manifiesto y reapunta la referencia a la copia local. Un libro que depende de un servidor es un libro que deja de funcionar sin conexión.
- Cuándo no es esto
- Un hipervínculo en tu prosa hacia un sitio externo está bien y no es lo que se reporta acá. La regla es sobre recursos necesarios para renderizar, no sobre destinos que el lector puede elegir visitar.
OPF-003 — El ítem existe en el EPUB pero no está declarado en el manifiesto OPF
Lo que imprime epubcheck:
Item "%1$s" exists in the EPUB, but is not declared in the OPF manifest.
- Qué significa
- El mismo hecho que RSC-008, reportado desde el lado del paquete: hay un archivo en el contenedor que el manifiesto nunca menciona.
- Por qué pasa
- Restos, la mayoría de las veces — una portada sin usar, el backup de un editor, fuentes de un diseño reemplazado, metadatos del sistema operativo que entraron al ZIP.
- El arreglo
- Decláralo si el libro lo necesita; bórralo del contenedor si no. Un archivo no declarado igual se distribuye y le cuesta a tu lector la descarga.
- Cuándo no es esto
- RSC-007 es una referencia sin archivo. Esto es un archivo sin referencia. El reporte se lee casi igual; los arreglos van en direcciones opuestas.
OPF-014 — La propiedad debería estar declarada en el archivo OPF
Lo que imprime epubcheck:
The property "%1$s" should be declared in the OPF file.
- Qué significa
- Un documento de contenido usa una función — scripting, MathML, SVG, un recurso remoto — que su ítem del manifiesto debería anunciar mediante el atributo properties, y no lo hace.
- Por qué pasa
- Una portada en SVG o un elemento svg en línea agregado después de exportar, MathML pegado de otra fuente, o un script sumado para una figura interactiva.
- El arreglo
- Agrega al atributo properties de ese ítem la propiedad que epubcheck nombra. Varias propiedades sobre un mismo ítem se separan con espacios.
- Cuándo no es esto
- OPF-015 es la imagen espejada: una propiedad declarada para una función que el archivo no usa. Agregar propiedades «por si acaso» cambia este error por aquel.
OPF-030 — No se encontró el unique-identifier
Lo que imprime epubcheck:
The unique-identifier "%1$s" was not found.
- Qué significa
- El atributo unique-identifier del elemento package apunta al id de un dc:identifier, y no existe ningún elemento con ese id.
- Por qué pasa
- Se reescribió el identificador — un ISBN nuevo, un UUID regenerado — y su atributo id se borró o se renombró mientras el atributo del package seguía apuntando al nombre viejo.
- El arreglo
- Dale un id al dc:identifier y haz que unique-identifier en el elemento package nombre exactamente ese id. Los dos strings tienen que coincidir carácter por carácter.
- Cuándo no es esto
- Esto es sobre el puntero, no sobre el valor. Un libro con un ISBN perfectamente válido falla igual acá si nada apunta a él, así que no busques un problema en el identificador mismo.
PKG-006 — Falta la entrada mimetype o no es el primer archivo del archivo comprimido
Lo que imprime epubcheck:
Mimetype file entry is missing or is not the first file in the archive.
- Qué significa
- El ZIP está mal armado. epubcheck llega hasta acá antes de leer una sola línea de tu contenido, y por eso el resto del reporte puede verse extrañamente corto.
- Por qué pasa
- Un re-zip a mano, o hecho con el compresor del sistema operativo, que ordena las entradas alfabéticamente y pone META-INF primero.
- El arreglo
- Rearma el archivo comprimido con la entrada mimetype agregada primero y guardada sin comprimir, y después todo lo demás. La mayoría de las herramientas de exportación EPUB ya lo hacen — el arreglo suele ser dejar de re-comprimir la carpeta a mano.
- Cuándo no es esto
- Nada de esto es un problema de contenido. No busques en tu XHTML: ninguna edición dentro del libro va a limpiar esta línea.
PKG-007 — El archivo mimetype solo debería contener la cadena y no estar comprimido
Lo que imprime epubcheck:
Mimetype file should only contain the string "application/epub+zip" and should not be compressed.
- Qué significa
- La entrada mimetype está en el lugar correcto, pero su contenido o su forma de almacenamiento están mal.
- Por qué pasa
- Un editor de texto que agregó un salto de línea o una marca BOM, o un paso de compresión que comprimió la entrada junto con todo lo demás.
- El arreglo
- Escribe exactamente los veinte caracteres application/epub+zip — sin salto de línea final, sin BOM — y agrega la entrada al archivo comprimido almacenada, no deflactada.
- Cuándo no es esto
- PKG-006 es sobre dónde está la entrada; esto es sobre qué contiene y cómo se guardó. Arreglar uno y volver a validar suele hacer aparecer el otro.
HTM-004 — DOCTYPE irregular
Lo que imprime epubcheck:
Irregular DOCTYPE: found "%1$s", expected "%2$s".
- Qué significa
- Un documento de contenido lleva una declaración de doctype que EPUB 3 no espera.
- Por qué pasa
- Un doctype de XHTML 1.1 o de EPUB 2 que sobrevivió a una conversión, o un doctype con un subconjunto interno para que el archivo pueda usar entidades HTML con nombre.
- El arreglo
- Reemplaza toda la declaración por <!DOCTYPE html>. Si el archivo dependía de entidades con nombre, cámbialas por referencias numéricas o por los caracteres literales — un subconjunto interno no es la forma de conservarlas.
- Cuándo no es esto
- Esto no es sobre la declaración XML de la primera línea. Es otra cosa, está permitida, y quitarla no va a limpiar este error.
NCX-001 — El identificador del NCX no coincide con el del OPF
Lo que imprime epubcheck:
NCX identifier ("%1$s") does not match OPF identifier ("%2$s").
- Qué significa
- La tabla de contenidos NCX heredada lleva un valor dtb:uid que no coincide con el dc:identifier del documento de paquete.
- Por qué pasa
- Se regeneró el identificador del OPF — un ISBN nuevo para una edición nueva, un UUID fresco de una exportación — y el NCX se quedó con el viejo.
- El arreglo
- Copia el valor del dc:identifier del OPF dentro del <meta name="dtb:uid"> del NCX. Si ya no das soporte a lectores EPUB 2, quitar el NCX por completo también es una respuesta válida.
- Cuándo no es esto
- Esto no significa que tu tabla de contenidos esté rota. La navegación de EPUB 3 vive en el documento nav; el NCX es la copia de compatibilidad que lo acompaña, y acá solo está en cuestión su identificador.