EPUBCheck messages explained
EPUBCheck reports every problem in an EPUB as a code such as RSC-005 or OPF-014 with a severity. This reference lists all 246 messages of EPUBCheck 5.4.0 with their official text, and explains causes and fixes for 144 of them.
Updated:
Severities
- Fatal error
- EPUBCheck could not continue checking this part of the EPUB. The file is invalid.
- Error
- The EPUB breaks a rule of the specification and is invalid. Stores and Send to Kindle may reject it, and EPUBCheck exits with status 1.
- Warning
- The EPUB is still valid, but something is likely to cause problems in some reading apps. EPUBCheck exits with 0 unless you pass --failonwarnings.
- Usage
- Informative only and hidden by default: it appears when EPUBCheck runs with -u (--usage). It does not make the EPUB invalid.
- Info
- Informative only. It does not make the EPUB invalid.
- Suppressed
- EPUBCheck does not report this message by default. It only appears if a custom message file (-c) changes its severity.
PKG: Package and ZIP container
The EPUB file itself: the ZIP archive, the mimetype file, file names and extensions.
| Code | Default severity | Message |
|---|---|---|
PKG-001 | Warning | Validating the EPUB against version … but detected version …. |
PKG-003 | Error | Unable to read EPUB file header. This is likely a corrupted EPUB file. |
PKG-004 | Fatal error | Corrupted EPUB ZIP header. |
PKG-005 | Error | The mimetype file has an extra field of length …. 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"… |
PKG-008 | Fatal error | Unable to read file "…". |
PKG-009 | Error | The file name "…" contains characters that are not allowed in OCF file names: …. |
PKG-010 | Warning | The file name "…" contains spaces, which may create interoperability issues with older reading systems. |
PKG-011 | Error | The file name "…" is not allowed to end with ".". |
PKG-012 | Usage | The file name "…" 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 "…". |
PKG-015 | Fatal error | Unable to read EPUB contents: … |
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 error | The EPUB file could not be found. |
PKG-020 | Error | OPF file "…" could not be found. |
PKG-021 | Error | Corrupted image file encountered. |
PKG-022 | Warning | Wrong file extension for image. The image is a "…" file but has the file extension "…". |
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 "…" in "…"). |
PKG-027 | Fatal error | Could not extract EPUB ZIP content, probably due to file names not encoded in UTF-8. |
RSC: Resources and references
Files and links between them: missing files, broken references, URLs, encodings and XML parsing.
| Code | Default severity | Message |
|---|---|---|
RSC-001 | Error | File "…" could not be found. |
RSC-002 | Fatal error | 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 "…" is encrypted, its content will not be checked. |
RSC-005 | Error | Error while parsing file: … |
RSC-006 | Error | Remote resource reference is not allowed in this context; resource "…" must be located in the EPUB container. |
RSC-006b | Usage | Resource "…" is located outside the EPUB Container; please check the resource is retrieved in scripted content. |
RSC-007 | Error | Referenced resource "…" could not be found in the EPUB. |
RSC-007w | Warning | Referenced resource "…" could not be found in the EPUB. |
RSC-008 | Error | Referenced resource "…" 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 error | Fatal Error while parsing file: … |
RSC-017 | Warning | Warning while parsing file: … |
RSC-019 | Warning | EPUBs with Multiple Renditions should contain a META-INF/metadata.xml file. |
RSC-020 | Error | "…" is not a valid URL (…) |
RSC-021 | Error | A Search Key Map Document must point to Content Documents ("…" 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: … |
RSC-025 | Usage | Informative parsing error: … |
RSC-026 | Error | URL "…" 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 … 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 "…". |
RSC-031 | Warning | Remote resource references should use HTTPS, but found "…". |
RSC-032 | Error | Fallback must be provided for foreign resources, but found none for resource "…" of type "…". |
RSC-033 | Error | Relative URL strings must not have a query component, but found one in "…". |
RSC-034 | Error | Scripts must have a JavaScript media type. |
RSC-035 | Usage | "…" is a legacy media type for JavaScript. Consider using 'text/javascript' instead. |
RSC-036 | Usage | … |
OPF: Package document (OPF)
The package document: metadata, manifest, spine, properties and fallbacks.
| Code | Default severity | Message |
|---|---|---|
OPF-001 | Error | There was an error when parsing the EPUB version: …. |
OPF-002 | Fatal error | The OPF file "…" was not found in the EPUB. |
OPF-003 | Usage | Item "…" 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 "…": must be a valid non-colonized name (aka "NCName"). |
OPF-004c | Error | Invalid prefix declaration: prefix "…" must be immediately followed by a colon character (":"). |
OPF-004d | Error | Invalid prefix declaration: prefix "…" 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 "…" doesn’t exist. |
OPF-006 | Error | Invalid prefix declaration: URI "…" is not a valid URI. |
OPF-007 | Warning | Re-declaration of reserved prefix "…". |
OPF-007a | Error | Invalid prefix mapping: prefix "_" must not be declared. |
OPF-007b | Error | Invalid prefix mapping: default vocabulary "…" 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: "…". |
OPF-011 | Error | itemref can’t have both page-spread-right and page-spread-left properties. |
OPF-012 | Error | Item property "…" is not defined for media type "…". |
OPF-013 | Warning | Resource "…" is declared with MIME type "…" in content, but has MIME type "…" in the package document. |
OPF-014 | Error | The property "…" should be declared in the OPF file. |
OPF-015 | Error | The property "…" 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: "…". |
OPF-025 | Error | Property value list "…" is not allowed, only one value must be specified. |
OPF-026 | Error | Found malformed property value: "…". |
OPF-027 | Error | Undefined property: "…". |
OPF-028 | Error | Undeclared prefix: "…". |
OPF-029 | Error | The file "…" does not appear to match the media type …, as specified in the OPF file. |
OPF-030 | Error | The unique-identifier "…" was not found. |
OPF-031 | Error | File listed in reference element in guide was not declared in OPF manifest: …. |
OPF-032 | Error | Guide references "…" 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 "…". |
OPF-035 | Warning | Media type "text/html" is not appropriate for XHTML/OPS. |
OPF-036 | Usage | Video type "…" might not be supported by reading systems |
OPF-037 | Warning | Found deprecated media-type "…". |
OPF-038 | Warning | Media type "…" is not appropriate for an OEBPS 1.2 context; Use "text/x-oeb1-document" instead. |
OPF-039 | Warning | Media-type "…" is not appropriate in an OEBPS 1.2 context. Use "text/x-oeb1-css" instead. |
OPF-040 | Error | Fallback item with id "…" could not be found. |
OPF-041 | Error | Fallback-style item with id "…" could not be found. |
OPF-042 | Error | "…" is not a permissible spine media-type. |
OPF-043 | Error | Spine item with non-standard media-type "…" has no fallback. |
OPF-044 | Error | Spine item with non-standard media-type "…" has no EPUB content document fallback. |
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 "…" 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-051 | Suppressed | Image dimensions exceed recommended size. |
OPF-052 | Error | Role value "…" is not valid. |
OPF-053 | Warning | Date value "…" does not follow recommended syntax as per http://www.w3.org/TR/NOTE-datetime:…. |
OPF-054 | Error | Date value "…" is not valid as per http://www.w3.org/TR/NOTE-datetime:…. |
OPF-055 | Warning | … tag is empty. |
OPF-057 | Suppressed | Image file length exceeds recommended size. |
OPF-060 | Error | Duplicate entry in the ZIP file: "…" (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 "…" was not found in the manifest. |
OPF-064 | Info | OPF declares type "…", validating using profile "…". |
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 "…" must not be listed both as a "link" element in the package metadata and as a manifest item. |
OPF-070 | Warning | Custom collection role "…" is an invalid URL. |
OPF-071 | Error | Index collections must only contain resources pointing to XHTML Content Documents. |
OPF-072 | Usage | Metadata element "…" is empty. |
OPF-073 | Error | External identifiers must not appear in the document type declaration. |
OPF-074 | Error | Package resource "…" is declared in several manifest items. |
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 "…" (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 "…" which is neither a Search Key Map Document nor an XHTML Content Document. |
OPF-085 | Warning | "dc:identifier" value "…" is marked as a UUID, but is an invalid UUID. |
OPF-086 | Warning | Property "…" is deprecated. Consider using … instead. |
OPF-086b | Usage | epub:type value "…" is deprecated. Consider using … instead. |
OPF-086c | Warning | the "…" reserved prefix is deprecated. |
OPF-087 | Usage | epub:type value "…" is not allowed on documents of type "…". |
OPF-088 | Usage | Unrecognized epub:type value "…". |
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 "…" instead of "…". |
OPF-091 | Error | The item href URL must not have a fragment identifier. |
OPF-092 | Error | Language tag "…" is not well-formed: … |
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 "…" links. |
OPF-095 | Error | The "media-type" attribute of "voicing" links must be an audio MIME type, but found "…". |
OPF-096 | Error | Non-linear content must be reachable, but found no hyperlink to "…". |
OPF-096b | Usage | No hyperlink was found to non-linear document "…", please check that it can be reached from scripted content. |
OPF-097 | Usage | Resource "…" 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 "…". |
OPF-099 | Error | The manifest must not list the package document. |
OPF-100 | Usage | The "…" property only applies to pre-paginated content. |
HTM: XHTML content documents
The XHTML chapters: DOCTYPE, entities, namespaces and fixed-layout viewports.
| Code | Default severity | Message |
|---|---|---|
HTM-001 | Error | Any publication resource that is an XML-based media type must be a valid XML 1.0 document. XML version found: …. |
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: …. |
HTM-004 | Error | Irregular DOCTYPE: found "…", expected "…". |
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 "…" 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 "…" 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 "…" 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 ("…") must not include the string "…" in its domain. |
HTM_055 | Usage | The "…" element should not be used (discouraged construct) |
HTM_056 | Error | Viewport metadata has no "…" dimension (both "width" and "height" properties are required) |
HTM_057 | Error | Viewport "…" value must be a positive number or the keyword "device-…" |
HTM_058 | Error | HTML documents must be encoded in UTF-8, but UTF-16 was detected. |
HTM_059 | Error | Viewport "…" property must not be defined more than once, but found values […]. |
HTM_060a | Usage | EPUB reading systems must ignore secondary viewport meta elements in fixed-layout documents; viewport declaration "…" will be ignored. |
HTM_060b | Usage | EPUB reading systems must ignore viewport meta elements in reflowable documents; viewport declaration "…" will be ignored. |
HTM_061 | Error | "…" 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 ("…") should be equal to the "href" attribute value ("…"). |
CSS: Stylesheets
CSS files and style elements: forbidden properties, encodings, fonts and syntax.
| Code | Default severity | Message |
|---|---|---|
CSS-001 | Error | The "…" property must not be included in an EPUB Style Sheet. |
CSS-002 | Error | Empty or NULL reference found. |
CSS-003 | Warning | CSS document is encoded in UTF-16. It should be encoded in UTF-8 instead. |
CSS-004 | Error | CSS documents must be encoded in UTF-8, detected …; |
CSS-005 | Usage | Conflicting alternate style tags found: …. |
CSS-006 | Usage | CSS selector specifies fixed position. |
CSS-007 | Info | Font-face reference "…" refers to non-standard font type "…". |
CSS-008 | Error | An error occurred while parsing the CSS: …. |
CSS-015 | Error | Alternative style sheets must have a title. |
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 "…" but no "…" 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. |
NCX: NCX (EPUB 2 table of contents)
The legacy NCX table of contents.
MED: Images, audio and media overlays
Image formats and headers, and synchronised audio (media overlays).
| Code | Default severity | Message |
|---|---|---|
MED-003 | Error | Picture "img" elements must reference core media type resources, but found resource "…" of type "…". |
MED-004 | Error | Image file header may be corrupted. |
MED-005 | Error | Media Overlay audio reference … to non-standard audio type … found. |
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_007 | Error | Picture "source" elements must define a "type" attribute when they reference foreign resources; found resource "…" of type "…". |
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 '#…'. |
MED_015 | Usage | Media overlay text references must be in reading order. Text target "…" is before the previous link target in … 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 '#…'. |
MED_018 | Warning | URL fragment should be an SVG fragment identifier, but found '#…'. |
ACC: Accessibility
Accessibility checks on content documents (most are suppressed by default).
| Code | Default severity | Message |
|---|---|---|
ACC-004 | Suppressed | Html "a" element must have text. |
ACC-005 | Suppressed | Table heading cells should be identified by "th" elements for accessibility. |
ACC-006 | Suppressed | Tables should include a "thead" element for accessibility. |
ACC-007 | Suppressed | Content Documents do not use "epub:type" attributes for semantic inflection. |
ACC-009 | Usage | MathML should either have an "alttext" attribute or "annotation-xml" child element. |
ACC-011 | Usage | SVG hyperlink has no accessible name |
ACC-012 | Suppressed | Table elements should include a caption element. |
OBS: Obsolete features
Features that still work but are outdated.
| Code | Default severity | Message |
|---|---|---|
OBS-001 | Usage | Usage of … is outdated. |
INF: Information
Notes about EPUBCheck itself.
| Code | Default severity | Message |
|---|---|---|
INF-001 | Info | Rule … is under review and its severity may change in a future release. See the discussion at … |
CHK: EPUBCheck configuration
Problems with EPUBCheck's own custom message file, not with the EPUB.
| Code | Default severity | Message |
|---|---|---|
CHK-001 | Error | The custom message overrides file was not found. |
CHK-002 | Error | Unrecognized custom message id … encountered in message overrides file "…". |
CHK-003 | Error | Unrecognized custom message severity "…" encountered in message overrides file "…". |
CHK-004 | Error | The custom message contains too many parameters in message overrides file "…". |
CHK-005 | Error | The custom suggestion contains too many parameters in message overrides file "…". |
CHK-006 | Error | Unable to parse the custom format parameter in message overrides file "…". |
CHK-007 | Error | Error encountered while processing custom message file "…": "…". |
CHK-008 | Error | Error encountered while processing an item "…"; skip other checks for the item. |
Retired message IDs
These IDs still exist in EPUBCheck's list of messages but have no text and are suppressed by default, so EPUBCheck never reports them unless a custom message file turns them on.
ACC-001, ACC-002, ACC-003, ACC-008, ACC-010, ACC-013, ACC-014, ACC-015, ACC-016, ACC-017, CSS-009, CSS-010, CSS-011, CSS-012, CSS-013, CSS-016, CSS-017, CSS-020, CSS-021, CSS-022, CSS-023, CSS-024, CSS-025, HTM-006, HTM-008, HTM-012, HTM-013, HTM-014, HTM-014a, HTM-015, HTM-016, HTM-017, HTM-018, HTM-019, HTM-020, HTM-021, HTM-022, HTM-023, HTM-024, HTM-027, HTM-028, HTM-029, HTM-033, HTM-036, HTM-038, HTM-049, HTM-050, HTM_053, MED-001, MED-002, MED_006, NAV-002, NCX-002, NCX-003, NCX-005, OPF-008, OPF-009, OPF-019, OPF-020, OPF-046, OPF-056, OPF-058, OPF-059, OPF-068, OPF-069, RSC-018, RSC-023, SCP-001, SCP-002, SCP-003, SCP-004, SCP-005, SCP-006, SCP-007, SCP-008, SCP-009, SCP-010
Source and licence
Message texts and default severities come from EPUBCheck 5.4.0, the W3C's EPUB validator, released under the BSD-3-Clause licence. Copyright © 2007 Adobe Systems Incorporated. Copyright © 2008 IDPF. Copyright © 2017 W3C (MIT, ERCIM, Keio, Beihang). github.com/w3c/epubcheck
Causes and fixes are written by EPUBLab. Codes without an explanation show only the official message and are not offered to search engines until we write one. EPUBLab is not affiliated with the W3C.