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_001 usage "img" or "area" HTML element has no "alt" attribute.
Explanation All meaningful non-text content that is presented to the user should have a textual alternative that describes the content. The "alt" attribute can be used for "img" and "area" HTML elements.
ACC_002 usage "input" HTML element is not referenced by a corresponding label element.
Explanation Labels that identify the controls in a form should be used so that users know what input data is expected.
ACC_008 usage Navigation Document has no "landmarks nav" element.
Explanation Landmarks are convenient for users to quickly jump from one part of the content to another. Their presence facilitates the use by people with access problems to the content.
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 warning 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.
ACC_013 usage Content file contains at least one inline style declaration.
Explanation Inline styles in HTML code almost always overwrite externally linked style sheets, including custom, user-defined style sheets that can help visually impaired people adapt content to their needs (enlarged fonts, color scheme, etc.). For this reason, the use of embedded styles should be avoided.
ACC_014 usage Value of CSS property "font-size" does not use a relative size: "%1$s"
Explanation The use of fixed units of measurement can create problems with some reading solutions when the user changes the font size and line-height settings, making the content unreadable. It is suggested to always use relative units of measure.
ACC_015 usage Value of CSS property "line-height" does not use a relative size.
Explanation The use of fixed units of measurement can create problems with some reading solutions when the user changes the font size and line-height settings, making the content unreadable. It is suggested to always use relative units of measure.
ACC_016 usage Value of CSS property "font-size" should use a relative size: "%1$s"
Explanation The use of fixed units of measurement can create problems with some reading solutions when the user changes the font size and line-height settings, making the content unreadable. It is suggested to always use relative units of measure.
ACC_017 usage Value of CSS property "line-height" does not use a relative size.
Explanation The use of fixed units of measurement can create problems with some reading solutions when the user changes the font size and line-height settings, making the content unreadable. It is suggested to always use relative units of measure.
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 error Only UTF-8 and UTF-16 encodings are allowed, detected %1$s.
Explanation Check the encoding of the CSS file and transform it into UTF-8 or UTF-16 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 error 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_009 usage Use of certain CSS such as Columns, Transforms, Transitions, box-sizing or KeyFrames can cause pagination issues.
CSS_010 error Stylesheet of type other than "text/css" must have a fallback.
Explanation For other types of style sheets other than CSS (e.g. XPGT), a CSS fallback must be provided.
CSS_012 usage Document links to multiple CSS files.
CSS_013 usage CSS property is declared !Important.
CSS_015 error Alternate Stylesheet has no title.
Explanation Alternative style sheets must have a title to be identified.
CSS_017 usage CSS selector specifies absolute position.
CSS_019 warning CSS font-face declaration has no attributes.
Explanation The declaration `@font-face` should contain at least the descriptors `font-family` and `src`.
CSS_020 error CSS font selector declaration uses unexpected font-size value "%1$s".
CSS_021 usage Shorthand CSS property "font-family" specifies an invalid System Font.
CSS_022 usage CSS selector specifies global margin setting.
CSS_023 usage CSS selector specifies media query.
CSS_024 usage CSS class Selector is not used.
CSS_025 usage CSS class Selector could not be found.
CSS_028 usage Use of Font-face declaration.
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_006 usage An XHTML Named Entity was found.
HTM_007 warning Empty or whitespace-only value of attribute ssml:ph.
HTM_008 error The src attribute is required.
HTM_009 error The DOCTYPE provided is obsolete or irregular and can be removed.
HTM_010 usage Namespace uri "%1$s" was found.
HTM_011 error Entity is undeclared.
HTM_012 usage Found a link to a CFI in an external book.
HTM_013 usage Intra-Publication CFIs found in document.
HTM_014 warning Invalid file extension for HTML file, expecting (html, htm or xhtml).
HTM_014a warning XHTML Content Document file name "%1$s" should have the extension ".xhtml".
HTM_017 error Content file has different language value in attributes xml:lang and lang.
HTM_018 usage Content file has invalid language value at attribute xml:lang.
HTM_019 usage Content file has invalid language definition at attribute lang.
HTM_020 usage Content file doesn’t contain xml:lang attribute.
HTM_021 usage Content file doesn’t contain lang attribute.
HTM_022 usage Document may contain excessive DIV or SPAN tags.
HTM_025 warning Non-registered URI scheme type found in href.
HTM_027 usage List contains less than 2 items.
HTM_028 usage Input html elements should include an id.
HTM_029 usage Label html elements should include a "for" attribute referencing the id of an input element.
HTM_033 usage HTML "head" element does not have a "title" child element.
HTM_044 usage Namespace uri "%1$s" was included but not used.
HTM_045 usage Encountered empty href.
HTM_046 error Fixed format item has no viewport defined.
HTM_047 error Html viewport is missing height and/or width.
HTM_048 error SVG Fixed-Layout Documents must have a "viewBox" attribute (on the outermost "svg" element).
HTM_049 error Html element does not have an xmlns set to "http://www.w3.org/1999/xhtml".
HTM_050 usage Found epub:type="pagebreak" attribute in content document.
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_053 info Found an external file link (file://) in file: "%1$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_001 error Video poster must have core media image type.
Explanation EPUB specifications require all reading solutions to support certain image formats. A file in this format must be used as a poster frame for videos.
MED_002 error %1$s element doesn’t provide fallback.
Explanation All resources that are not in the formats listed among the Core Media Types must have a fallback in a Core Media Types format, in order to allow content to be enjoyed in all reading solutions (even those with a minimum media type support).
MED_003 error A manifest fallback must be provided for image 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_006 usage Some browsers do not support rendering SVG images which use a filename in the xlink:href property.
MED_007 error Foreign resources can only be referenced from "source" elements with an explicit "type" attribute; found resource "%1$s" of foreign type "%2$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_002 usage Found epub:type="page-list" in nav document
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_002 error toc attribute was not found on the spine element.
Explanation In the OPF file, the id of the TOC element (i.e. NCX file) must be present as the value of the attribute "toc" of the element "spine".
NCX_003 usage An .NCX file is required for TOC navigation on EPUB v2 readers.
NCX_004 usage NCX identifier ("dtb:uid" metadata) should not contain leading or trailing whitespace.
NCX_005 usage Found ncx "page-list" in .ncx file
NCX_006 usage Empty "text" label in the NCX document
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 warning 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_008 error Handler binding for core Media-type "%1$s" is not allowed.
OPF_009 error The media-type "%1$s" has already been assigned a handler, with ID "%2$s".
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 error The type property "%1$s" on the object tag does not match the declared media-type "%2$s" in the OPF manifest.
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_019 fatal Spine tag was not found in the OPF file.
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_046 error Scripted property is not set on mediaType handler.
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://www.w3.org/TR/NOTE-datetime:%2$s.
OPF_054 error Date value "%1$s" is not valid as per http://www.w3.org/TR/NOTE-datetime:%2$s.
OPF_055 warning %1$s tag is empty.
OPF_056 usage Media type "%1$s" is not a core audio type.
OPF_058 usage Spine item "%1$s" is not referenced from the TOC in the Nav Doc.
OPF_059 usage Spine item "%1$s" is not referenced from the TOC in the NCX.
OPF_060 error Duplicate entry in the ZIP file: "%1$s".
OPF_061 warning Duplicate entry in the ZIP file (after Unicode NFC normalization) "%1$s".
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_068 error Unknown collection role "%1$s".
OPF_069 error Custom collection role URI "%1$s" must not include the string "idpf.org" in its host component.
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_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".
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 Mimetype file should only contain the string "application/epub+zip" and should not be compressed.
PKG_008 fatal Unable to read file "%1$s".
PKG_009 error File name contains characters that are not allowed in OCF file names: "%1$s".
PKG_010 warning Filename contains spaces, therefore URI escaping is necessary. Consider removing spaces from filename.
PKG_011 error Filename is not allowed to end with ".".
PKG_012 usage File name contains the following non-ascii characters: %1$s. Consider changing the filename.
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 info Uncommon EPUB file extension.
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" could not be decrypted.
RSC_005 error Error while parsing file: %1$s
RSC_006 error Remote resource reference not allowed; resource must be placed in the OCF.
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 error Fragment identifier is used in a reference to a stylesheet resource.
RSC_014 error Fragment identifier defines an incompatible resource type.
RSC_015 error 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_018 warning Alternative image file "%1$s" could not be found.
RSC_019 warning EPUBs with Multiple Renditions should contain a META-INF/metadata.xml file.
RSC_020 error %1$s" is not a valid URI.
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_023 warning Couldn’t parse host of URL "%1$s" (probably due to disallowed characters or missing slashes after the protocol)
SCP_001 usage Use of Javascript eval() function in EPUB scripts is a security risk.
SCP_002 usage Use of XMLHttpRequest in EPUB scripts is a security risk.
SCP_003 usage Local and Session Storage is not currently supported.
SCP_004 error Content file contains script which is not supported in EPUB v2.
SCP_006 usage Inline scripts found.
SCP_007 usage Script references "innerHtml".
SCP_008 usage Script references "innerText".
SCP_009 usage Content file uses mouse event handlers.
SCP_010 usage Epub 3 content file contains script.