Messages

This is the reference documentation for EPUBCheck messages.

Whenever it detects a conformance issue (or other noteworthy information) with your content, EPUBCheck reports a message. A message consists of several pieces of information:

  • a severity level indicates if it is a fatal error, an error, a warning, an information, or a usage message. See the severity levels section below for more details.
  • a message code is used to uniquely identify the issue among the reference list of possible messages
  • a location indicates in which file (possibly with a line and column number) the issue was detected
  • a text content describes the reported issue in plain language

§ Severity Levels

The messages reported by EPUBCheck use the following severity level:

Fatal Error
An error which prevents EPUBCheck from further processing the content. This may be caused by a bug in EPUBCheck, or an unforeseen condition (like an I/O error).
Error
A failure to match an EPUB conformance requirement. In the EPUB specifications, these requirements are identified with “MUST”, “MUST NOT”, or “REQUIRED” keywords.
Warning
A deviation from an EPUB recommended practice. In the EPUB specifications, these recommendations are identified with “SHOULD”, “SHOULD NOT”, or “RECOMMENDED” keywords
Info
A noteworthy information about your content.
Usage
A minor information about your content.

§ Message Codes

EPUBCheck Message Codes
Code Severity Message
ACC_009 usage MathML should either have an "alttext" attribute or "annotation-xml" child element.
Explanation All meaningful non-text content that is presented to the user should have a textual alternative that describes the content. The "alttext" attribute or "annotation-xml" child element can be used for MathML content.
ACC_011 usage SVG hyperlinks should have a human-readable title (using the "title" child element or the "xlink:title" attribute).
Explanation Visual interactive content that is presented to the user should have a textual alternative. The "title" child element or the "xlink:title" attribute can be used for SVG links.
CHK_001 error The custom message overrides file was not found.
CHK_002 error Unrecognized custom message id %1$s encountered in message overrides file "%2$s".
CHK_003 error Unrecognized custom message severity "%1$s" encountered in message overrides file "%2$s".
CHK_004 error The custom message contains too many parameters in message overrides file "%1$s".
CHK_005 error The custom suggestion contains too many parameters in message overrides file "%1$s".
CHK_006 error Unable to parse the custom format parameter in message overrides file "%1$s".
CHK_007 error Error encountered while processing custom message file "%1$s": "%2$s".
CHK_008 error Error encountered while processing an item "%1$s"; skip other checks for the item.
CSS_001 error The "%1$s" property must not be included in an EPUB Style Sheet.
Explanation EPUB specifications says authors must not use the direction and unicode-bidi CSS properties. Use the HTML dir attribute to set the inline base direction, use bdo elements and dir attributes to control bidirectionality.
CSS_002 error Empty or NULL reference found.
Explanation A reference in the CSS code is empty or null. It could be an unset URL reference, e.g. `url('')` or `url()`.
CSS_003 warning CSS document is encoded in UTF-16. It should be encoded in UTF-8 instead.
Explanation Check the encoding of the CSS file and transform it into UTF-8 if necessary.
CSS_004 error Only UTF-8 and UTF-16 encodings are allowed, detected %1$s BOM.
Explanation Check the encoding of the CSS file and transform it into UTF-8 or UTF-16 if necessary.
CSS_005 usage Conflicting alternate style attributes found: %1$s.
CSS_006 usage CSS selector specifies fixed position.
CSS_007 info Font-face reference "%1$s" refers to non-standard font type "%2$s".
Explanation Font core-types are "TrueType", "OpenType", "WOFF" and "WOFF2"
CSS_008 error An error occurred while parsing the CSS: %1$s.
Explanation The file seems to have some problems that prevent it from being read or parsed.
CSS_015 error Alternative style sheets must have a title.
Explanation Alternative style sheets must have a title to be identified.
CSS-019 warning CSS font-face declaration has no attributes.
CSS_028 usage Use of Font-face declaration.
CSS-029 usage Found CSS class name "%1$s" but no "%2$s" property was declared in the package document.
CSS-030 error The package document declares media overlays styling class names but no CSS was found in the content document.
HTM_001 error Any publication resource that is an XML-based media type must be a valid XML 1.0 document. XML version found: %1$s.
HTM_002 warning The installed xml parser doesn’t support xml version verification. Xml files must be a valid XML 1.0 document.
HTM_003 error External entities are not allowed in EPUB v3 documents. External entity declaration found: %1$s.
HTM_004 error Irregular DOCTYPE: found "%1$s", expected "%2$s".
HTM_005 usage An external reference was found.
HTM_007 warning Empty or whitespace-only value of attribute ssml:ph.
HTM_009 error The DOCTYPE provided is obsolete or irregular and can be removed.
HTM_010 usage Namespace "%1$s" is unusual for the prefix "epub".
HTM_011 error Entity is undeclared.
HTM_025 warning Non-registered URI scheme type found in href.
HTM_044 usage Namespace uri "%1$s" was included but not used.
HTM_045 usage Encountered empty href.
HTM_046 error Fixed layout document has no "viewport" meta element.
HTM_047 error Viewport metadata "%1$s" has a syntax error
HTM_048 error SVG Fixed-Layout Documents must have a "viewBox" attribute (on the outermost "svg" element).
HTM_051 warning Found Microdata semantic enrichments but no RDFa. EDUPUB recommends using RDFa Lite.
HTM_052 error The property "region-based" is only allowed on nav elements in Data Navigation Documents.
HTM_054 error Custom attribute namespace ("%1$s") must not include the string "%2$s" in its domain.
HTM_055 usage The "%1$s" element should not be used (discouraged construct)
HTM_056 error Viewport metadata has no "%1$s" dimension (both "width" and "height" properties are required)
HTM_057 error Viewport "%1$s" value must be a positive number or the keyword "device-%1$s"
HTM_058 error HTML documents must be encoded in UTF-8, but UTF-16 was detected.
HTM_059 error Viewport "%1$s" property must not be defined more than once, but found values [%2$s].
HTM_060a usage EPUB reading systems must ignore secondary viewport meta elements in fixed-layout documents; viewport declaration "%1$s" will be ignored.
HTM_060b usage EPUB reading systems must ignore viewport meta elements in reflowable documents; viewport declaration "%1$s" will be ignored.
HTM_061 error "%1$s" is not a valid custom data attribute (it must have at least one character after the hyphen, be XML-compatible, and not contain ASCII uppercase letters).
HTM_062 usage SVG "xlink:href" attribute is deprecated; an "href" attribute should be used instead.
HTM_063 usage SVG "xlink:href" attribute value ("%1$s") should be equal to the "href" attribute value ("%2$s").
INF_001 info The previous rule is under review and its severity may change in a future release. See the discussion at %1$s
MED_003 error Picture "img" elements must reference core media type resources, but found resource "%1$s" of type "%2$s".
Explanation The image is not in a Core Media Types format, so a fallback image in a Core Media Types format is required.
MED_004 error Image file header may be corrupted.
Explanation The file looks corrupted, try opening it with an image viewer and replace it if necessary.
MED_005 error Media Overlay audio reference %1$s to non-standard audio type %2$s found.
Explanation Media Overlay resources can only be in one of the audio formats provided in the Core Media Types.
MED_007 error Picture "source" elements must define a "type" attribute when they reference foreign resources; found resource "%1$s" of type "%2$s".
MED-008 error The time specified in the clipBegin attribute must not be after clipEnd.
MED-009 error The time specified in the clipBegin attribute must not be the same as clipEnd.
MED_010 error EPUB Content Documents referenced from a Media Overlay must specify the "media-overlay" attribute.
MED_011 error EPUB Content Document referenced from multiple Media Overlay Documents.
MED_012 error The "media-overlay" attribute does not match the ID of the Media Overlay that refers to this document.
MED_013 error Media Overlay Document referenced from the "media-overlay" attribute does not contain a reference to this Content Document.
MED_014 error Media overlay audio file URLs must not have a fragment, but found '#%1$s'.
MED_015 usage Media overlay text references must be in reading order. Text target "%1$s" is before the previous link target in %2$s order.
MED_016 warning Media Overlays total duration should be the sum of the durations of all Media Overlays documents.
MED_017 warning URL fragment should indicate an element ID, but found '#%1$s'.
MED_018 warning URL fragment should be an SVG fragment identifier, but found '#%1$s'.
NAV_001 error The nav file is not supported for EPUB v2.
Explanation The EPUB 2 format does not support the nav file; to define the Content Table and PageList use the NCX file, for landmarks use the <guide> element in the OPF file.
NAV_003 error The Navigation Document must have a page list when content document(s) contain page breaks (epub:type="pagebreak").
Explanation Page breaks identify the points at which the paper pages of the document are interrupted. For this reason, if they are present, it is necessary to indicate the page number in the nav page list element.
NAV_004 usage The Navigation Document should contain the full document heading hierarchy in EDUPUB.
NAV_005 usage Content documents contain "audio" elements but the Navigation Document does not have a listing of audio clips (epub:type="loa").
NAV_006 usage Content documents contain "figure" elements but the Navigation Document does not have a listing of figures (epub:type="loi").
NAV_007 usage Content documents contain "table" elements but the Navigation Document does not have a listing of tables (epub:type="lot").
NAV_008 usage Content documents contain "video" elements but the Navigation Document does not have a listing of video clips (epub:type="lov").
NAV_009 error Region-based navigation links must point to Fixed-Layout Documents.
NAV_010 error "%1$s" nav must not link to remote resources; found link to "%2$s".
NAV_011 warning "%1$s" nav must be in reading order; link target "%2$s" is before the previous link’s target in %3$s order.
NCX_001 error NCX identifier ("%1$s") does not match OPF identifier ("%2$s").
Explanation Both fields should have the same value, i.e. the unique identifier of the publication.
NCX_004 usage NCX identifier ("dtb:uid" metadata) should not contain leading or trailing whitespace.
NCX_006 usage Empty "text" label in the NCX document
OBS-001 usage usage of %1$s is outdated.
OPF_001 error There was an error when parsing the EPUB version: %1$s.
OPF_002 fatal The OPF file "%1$s" was not found in the EPUB.
OPF_003 usage Item "%1$s" exists in the EPUB, but is not declared in the OPF manifest.
OPF_004 warning Invalid prefix declaration: leading or trailing whitespace is not allowed.
OPF_004a error Invalid prefix declaration: found empty prefix.
OPF_004b error Invalid prefix "%1$s": must be a valid non-colonized name (aka "NCName").
OPF_004c error Invalid prefix declaration: prefix "%1$s" must be immediately followed by a colon character (":").
OPF_004d error Invalid prefix declaration: prefix "%1$s" must be separated by its URI with a space.
OPF_004e warning Invalid prefix declaration: found illegal whitespace between prefix and URI.
OPF_004f warning Invalid prefix declaration: found illegal whitespace between prefix mappings.
OPF_005 error Invalid prefix declaration: URI for prefix "%1$s" doesn’t exist.
OPF_006 error Invalid prefix declaration: URI "%1$s" is not a valid URI.
OPF_007 warning Re-declaration of reserved prefix "%1$s".
OPF_007a error Invalid prefix mapping: prefix "_" must not be declared.
OPF_007b warning Invalid prefix mapping: default vocabulary "%1$s" must not be re-declared.
OPF-007c error Invalid prefix mapping: a prefix to the Dublin Core /elements/1.1/ namespace must not be declared
OPF_010 error Error resolving reference: "%1$s".
OPF_011 error itemref can’t have both page-spread-right and page-spread-left properties.
OPF_012 error Item property "%1$s" is not defined for media type "%2$s".
OPF_013 warning Resource "%1$s" is declared with MIME type "%2$s" in content, but has MIME type "%3$s" in the package document.
OPF_014 error The property "%1$s" should be declared in the OPF file.
OPF_015 error The property "%1$s" should not be declared in the OPF file.
OPF_016 error The element "rootfile" is missing its required attribute "full-path".
OPF_017 error The attribute "full-path" on element "rootfile" must not be empty.
OPF_018 warning The "remote-resources" property was declared in the Package Document, but no reference to remote resources has been found.
OPF_018b usage The "remote-resources" property was declared in the Package Document, but no reference to remote resources has been found; please check scripted content to make sure the property is legit.
OPF_021 warning Use of non-registered URI scheme type in href: "%1$s".
OPF_025 error Property value list "%1$s" is not allowed, only one value must be specified.
OPF_026 error Found malformed property value: "%1$s".
OPF_027 error Undefined property: "%1$s".
OPF_028 error Undeclared prefix: "%1$s".
OPF_029 error The file "%1$s" does not appear to match the media type %2$s, as specified in the OPF file.
OPF_030 error The unique-identifier "%1$s" was not found.
OPF_031 error File listed in reference element in guide was not declared in OPF manifest: %1$s.
OPF_032 error Guide references "%1$s" which is not a valid "OPS Content Document".
OPF_033 error The spine contains no linear resources.
OPF_034 error The spine contains multiple references to the manifest item with id "%1$s".
OPF_035 warning Media type "text/html" is not appropriate for XHTML/OPS.
OPF_036 usage Video type "%1$s" might not be supported by reading systems
OPF_037 warning Found deprecated media-type "%1$s".
OPF_038 warning Media type "%1$s" is not appropriate for an OEBPS 1.2 context; Use "text/x-oeb1-document" instead.
OPF_039 warning Media-type "%1$s" is not appropriate in an OEBPS 1.2 context. Use "text/x-oeb1-css" instead.
OPF_040 error Fallback item could not be found.
OPF_041 error Fallback-style item could not be found.
OPF_042 error %1$s" is not a permissible spine media-type.
OPF_043 error Spine item with non-standard media-type "%1$s" has no fallback.
OPF_044 error Spine item with non-standard media-type "%1$s" has a fallback to non-standard media-type.
OPF_045 error Encountered circular reference in fallback chain.
OPF_047 usage OPF file is using OEBPS 1.2 syntax allowing backwards compatibility.
OPF_048 error Package tag is missing its required unique-identifier attribute and value.
OPF_049 error Item id "%1$s" was not found in the manifest.
OPF_050 error TOC attribute references resource with non-NCX mime type; "application/x-dtbncx+xml" is expected.
OPF_052 error Role value "%1$s" is not valid.
OPF_053 warning Date value "%1$s" does not follow recommended syntax as per http://dristachi.site/TR/NOTE-datetime:%2$s.
OPF_054 error Date value "%1$s" is not valid as per http://dristachi.site/TR/NOTE-datetime:%2$s.
OPF_055 warning %1$s tag is empty.
OPF_058 usage Spine item "%1$s" is not referenced from the TOC in the Nav Doc.
OPF_060 error Duplicate entry in the ZIP file: "%1$s" (file names must be unique after Unicode canonical normalization and full case folding).
OPF_062 usage Found Adobe page-map attribute on spine element in opf file.
OPF_063 warning Referenced Adobe page-map item "%1$s" was not found in the manifest.
OPF_064 info OPF declares type "%1$s", validating using profile "%2$s".
OPF_065 error Invalid metadata declaration, probably due to a cycle in "refines" metadata.
OPF_066 error Missing "dc:source" or "source-of" pagination metadata. The pagination source must be identified using the "dc:source" and "source-of" properties when the content includes page break markers.
OPF_067 error The resource "%1$s" must not be listed both as a "link" element in the package metadata and as a manifest item.
OPF_070 warning Custom collection role "%1$s" is an invalid URI.
OPF_071 error Index collections must only contain resources pointing to XHTML Content Documents.
OPF_072 usage Metadata element "%1$s" is empty.
OPF_073 error External identifiers must not appear in the document type declaration.
OPF_074 error Package resource "%1$s" is declared in several manifest item.
OPF_075 error Preview collections must only point to EPUB Content Documents.
OPF_076 error The URI of preview collections link elements must not include EPUB canonical fragment identifiers.
OPF_077 warning A Data Navigation Document should not be included in the spine.
OPF_078 error An EPUB Dictionary must contain at least one Content Document with dictionary content (epub:type "dictionary").
OPF_079 warning Dictionary content was found (epub:type "dictionary"), the Package Document should declare the dc:type "dictionary".
OPF_080 warning A Search Key Map document file name should have the extension ".xml".
OPF_081 error Resource "%1$s" (referenced from an EPUB Dictionary collection) was not found.
OPF_082 error Found an EPUB Dictionary collection containing more than one Search Key Map Document.
OPF_083 error Found an EPUB Dictionary collection containing no Search Key Map Document.
OPF_084 error Found an EPUB Dictionary collection containing resource "%1$s" which is neither a Search Key Map Document nor an XHTML Content Document.
OPF_085 warning dc:identifier" value "%1$s" is marked as a UUID, but is an invalid UUID.
OPF_086 warning Property "%1$s" is deprecated. Consider using %2$s instead.
OPF_086b usage epub:type value "%1$s" is deprecated. Consider using %2$s instead.
OPF-086c warning the "%1$s" reserved prefix is deprecated.
OPF_087 usage epub:type value "%1$s" is not allowed on documents of type "%2$s".
OPF_088 usage Unrecognized epub:type value "%1$s".
OPF_089 error The "alternate" link rel keyword cannot be paired with other keywords.
OPF_090 usage It is encouraged to use MIME media type "%1$s" instead of "%2$s".
OPF-091 error The item href URL must not have a fragment identifier.
OPF-092 error Language tag "%1$s" is not well-formed: %2$s
OPF-093 error The "media-type" attribute is required for linked resources located in the EPUB container
OPF-094 error The "media-type" attribute is required for "%1$s" links.
OPF-095 error The "media-type" attribute of "voicing" links must be an audio MIME type, but found "%1$s".
OPF-096 error Non-linear content must be reachable, but found no hyperlink to "%1$s".
OPF-096b usage No hyperlink was found to non-linear document "%1$s", please check that it can be reached from scripted content.
OPF-097 usage Resource "%1$s" is listed in the manifest, but no reference to it was found in content documents.
OPF-098 error The "href" attribute must reference resources, not elements in the package document, but found URL "%1$s".
OPF-099 error The manifest must not list the package document.
OPF-100 usage The "%1$s" property only applies to pre-paginated content.
PKG_001 warning Validating the EPUB against version %1$s but detected version %2$s.
PKG_003 error Unable to read EPUB file header. This is likely a corrupted EPUB file.
PKG_004 fatal Corrupted EPUB ZIP header.
PKG_005 error The mimetype file has an extra field of length %1$s. The use of the extra field feature of the ZIP format is not permitted for the mimetype file.
PKG_006 error Mimetype file entry is missing or is not the first file in the archive.
PKG_007 error The content of the mimetype file must be the string "application/epub+zip"%1$s
PKG_008 fatal Unable to read file "%1$s".
PKG_009 error The file name "%1$s" contains characters that are not allowed in OCF file names: %2$s.
PKG_010 warning The file name "%1$s" contains spaces, which may create interoperability issues with older reading systems.
PKG_011 error The file name "%1$s" is not allowed to end with ".".
PKG_012 usage The file name "%1$s" contains non-ASCII characters, which might create interoperability issues with older reading systems.
PKG_013 error The EPUB file includes multiple OPS renditions.
PKG_014 warning The EPUB contains empty directory "%1$s".
PKG_015 fatal Unable to read EPUB contents: %1$s
PKG_016 warning Use only lowercase characters for the EPUB file extension for maximum compatibility.
PKG_017 warning Uncommon EPUB file extension.
PKG_018 fatal The EPUB file could not be found.
PKG_020 error OPF file "%1$s" could not be found.
PKG_021 error Corrupted image file encountered.
PKG_022 warning Wrong file extension for image. The image is a "%1$s" file but has the file extension "%2$s".
PKG_023 usage Validating the EPUB against version 2.0, default validation profile will be used.
PKG_024 usage Uncommon EPUB file extension.
PKG-025 error Publication resource must not be located in the META-INF directory
PKG-026 error Obfuscated resource must be a Font Core Media Type (was declared as "%1$s" in "%2$s").
PKG-027 fatal Could not extract EPUB ZIP content, probably due to file names not encoded in UTF-8.
RSC-001 error File "%1$s" could not be found.
RSC-002 FATAL Required META-INF/container.xml resource could not be found.
RSC-003 error No rootfile tag with media type "application/oebps-package+xml" was found in the container.
RSC-004 INFO File "%1$s" is encrypted, its content will not be checked.
RSC-005 error error while parsing file: %1$s
RSC-006 error Remote resource reference is not allowed in this context; resource "%1$s" must be located in the EPUB container.
RSC-006b usage Resource "%1$s" is located outside the EPUB Container; please check the resource is retrieved in scripted content.
RSC-007 error Referenced resource "%1$s" could not be found in the EPUB.
RSC-007w warning Referenced resource "%1$s" could not be found in the EPUB.
RSC-008 error Referenced resource "%1$s" is not declared in the OPF manifest.
RSC-009 warning A non-SVG image resource should not be defined with a fragment identifier.
RSC-010 error Reference to non-standard resource type found.
RSC-011 error Found a reference to a resource that is not a spine item.
RSC-012 error Fragment identifier is not defined.
RSC-013 usage Fragment identifier is used in a reference to a stylesheet resource.
RSC-014 usage Fragment identifier defines an incompatible resource type.
RSC-015 usage A fragment identifier is required for svg use tag references.
RSC-016 fatal Fatal error while parsing file: %1$s
RSC-017 warning warning while parsing file: %1$s
RSC-019 warning EPUBs with Multiple Renditions should contain a META-INF/metadata.xml file.
RSC-020 error "%1$s" is not a valid URL (%2$s)
RSC-021 error A Search Key Map Document must point to Content Documents ("%1$s" was not found in the spine).
RSC-022 INFO Cannot check image details (requires Java version 7 or higher).
RSC-024 usage Informative parsing warning: %1$s
RSC-025 usage Informative parsing error: %1$s
RSC-026 error URL "%1$s" leaks outside the container (it is not a valid-relative-ocf-URL-with-fragment string)
RSC-027 warning XML document is encoded in UTF-16. It should be encoded in UTF-8 instead.
RSC-028 error XML documents must be encoded in UTF-8, but %1$s was detected.
RSC-029 error Data URL is not allowed in this context.
RSC-030 error File URLs are not allowed in EPUB, but found "%1$s".
RSC-031 warning Remote resource references should use HTTPS, but found "%1$s".
RSC-032 error Fallback must be provided for foreign resources, but found none for resource "%1$s" of type "%2$s".
RSC-033 error Relative URL strings must not have a query component, but found one in "%1$s".
RSC-034 error Scripts must have a JavaScript media type.
RSC-035 usage "%1$s" is a legacy media type for JavaScript. Consider using 'text/javascript' instead.
RSC-036 usage %1$s