Skip to content
EPUBCheck · XHTML content documents

EPUBCheck HTM-003: external entity declared

Updated:

EPUBCheck HTM-003 is an error message: “External entities are not allowed in EPUB v3 documents. External entity declaration found: ….” An EPUB 3 document declares an external entity, which EPUB does not allow. External entities pull text from another file through the DOCTYPE, and reading apps do not resolve them, so the text would be missing.

The official message

External entities are not allowed in EPUB v3 documents. External entity declaration found: %1$s.

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

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

Typical causes

  • A DOCTYPE with an internal subset (the part in square brackets) that declares entities loaded from an external file.
  • XML exported from a publishing system that used entity files for shared text such as the book title.

How to fix it

  1. Open the file EPUBCheck names (the message gives the path, line and column) in a text or EPUB editor such as Sigil, or unzip the EPUB and open it there.
  2. Remove the entity declarations from the DOCTYPE; in XHTML chapters the DOCTYPE should be just <!DOCTYPE html>.
  3. Replace each use of the entity with the real text, or with a numeric character reference such as &#160; when it stood for a single character.
  4. Rebuild the EPUB and run EPUBCheck again to confirm the message is gone.

When it's not this

If an entity such as &nbsp; is used without being declared at all, that is HTM-011, not HTM-003.

Terms used here

Other HTM messages

  • HTM-004 Irregular DOCTYPE: found "…", expected "…".
  • HTM-001 Any publication resource that is an XML-based media type must be a valid XML 1.0 document. XML version found: ….
  • HTM-007 Empty or whitespace-only value of attribute ssml:ph.
  • HTM-009 The DOCTYPE provided is obsolete or irregular and can be removed.
  • HTM-010 Namespace "…" is unusual for the prefix "epub".
  • HTM-011 Entity is undeclared.

Sources

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

FAQ

What does EPUBCheck HTM-003 mean?

EPUBCheck HTM-003 is an error message: “External entities are not allowed in EPUB v3 documents. External entity declaration found: ….” An EPUB 3 document declares an external entity, which EPUB does not allow. External entities pull text from another file through the DOCTYPE, and reading apps do not resolve them, so the text would be missing.

Is HTM-003 an error?

HTM-003 is reported as error by default. 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.