Skip to content
EPUBCheck · Package and ZIP container

EPUBCheck PKG-001: EPUB version mismatch

Updated:

EPUBCheck PKG-001 is a warning message: “Validating the EPUB against version … but detected version ….” EPUBCheck was told to validate one EPUB version but the package document declares another. The version comes from the version attribute of the package element, and EPUBCheck reports the mismatch as a warning before it applies the rules of the version you asked for.

The official message

Validating the EPUB against version %1$s but detected version %2$s.

Default severity
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.
EPUBCheck version
5.4.0

%1$s, %2$s… are filled in with the file, value or element EPUBCheck found.

Typical causes

  • EPUBCheck was run with -v 2.0 or -v 3.0 and the file's package element has a different version attribute.
  • A build script or validation service that always passes the same -v option, whatever the book is.
  • A book half-converted from EPUB 2 to EPUB 3 whose version attribute was not updated.

How to fix it

  1. Run EPUBCheck without -v on a packaged .epub file: it reads the version from the package document.
  2. If the version attribute itself is wrong, set it to the version the content really follows: version="3.0" for EPUB 3.
  3. Validate again and fix the messages for the right version.

When it's not this

If EPUBCheck says it is validating against 2.0 with the default profile, that is the informative PKG-023, not a mismatch.

Terms used here

Other PKG messages

  • PKG-003 Unable to read EPUB file header. This is likely a corrupted EPUB file.
  • PKG-004 Corrupted EPUB ZIP header.
  • PKG-005 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 Mimetype file entry is missing or is not the first file in the archive.
  • PKG-007 The content of the mimetype file must be the string "application/epub+zip"…
  • PKG-008 Unable to read file "…".

Sources

Message text and severity from EPUBCheck 5.4.0 (W3C, BSD-3-Clause). Explanation by EpubCC.

FAQ

What does EPUBCheck PKG-001 mean?

EPUBCheck PKG-001 is a warning message: “Validating the EPUB against version … but detected version ….” EPUBCheck was told to validate one EPUB version but the package document declares another. The version comes from the version attribute of the package element, and EPUBCheck reports the mismatch as a warning before it applies the rules of the version you asked for.

Is PKG-001 an error?

PKG-001 is reported as warning by default. The EPUB is still valid, but something is likely to cause problems in some reading apps. EPUBCheck exits with 0 unless you pass --failonwarnings.