FixMyEPUB

EPUB metadata guide

How to fix EPUB cover metadata for Kindle

A cover image can be inside an EPUB and still go undiscovered. The important relationship is between the image file, its manifest item and the metadata that marks that item as the publication cover.

Updated September 17, 20266 minute read

First, locate the package document

Every EPUB container includes META-INF/container.xml. Its rootfile entry identifies the OPF package document. Do not assume the OPF is always named content.opf or always lives in an OEBPS folder; use the declared path.

The manifest item connects an ID to the image

The OPF manifest lists publication resources. A cover image item needs a unique ID, a relative href and an accurate media type. For example, the ID might be cover-image, but the exact text is not special—the references simply need to agree.

Paths are resolved relative to the OPF. If the package is in EPUB/package.opf and the image href is images/cover.jpg, the archive needs a matching resource at EPUB/images/cover.jpg.

EPUB 3 uses the cover-image property

In EPUB 3, the manifest item can include properties="cover-image". The W3C EPUB specification recommends marking the cover this way when a publication includes one. Only one image should be treated as the primary cover candidate.

EPUB 2 uses a metadata reference

Older EPUB 2 packages commonly include a metadata element with name="cover". Its content value is the ID of the cover image’s manifest item—not the filename. If the content points to a missing ID, the metadata is broken even when the image exists.

Compatibility rule: when the same valid manifest item is identified consistently by both EPUB 2 and EPUB 3 declarations, different readers and conversion paths have less ambiguity.

Do not forget the image media type

A JPG should normally be declared as image/jpeg, a PNG as image/png and an SVG as image/svg+xml. A mismatched or missing media type can prevent a strict processor from interpreting the resource as intended.

Safe repair sequence

  1. Parse container.xml and locate the OPF.
  2. Find an existing cover declaration or a clearly named image candidate.
  3. Resolve its path and confirm the file exists.
  4. Confirm the manifest ID is unique and the media type agrees with the file.
  5. Add or normalize the EPUB 3 cover-image property.
  6. Add or normalize the EPUB 2 metadata reference to the same ID.
  7. Rebuild the container and run the same checks on the output.

If no safe image exists, ask the user to select one. Automatically promoting the first small logo, ornament or publisher mark can create a technically valid but visibly wrong cover.

When metadata is not the cause

If the file, media type and both declarations already agree, repeated metadata edits are unlikely to help. Look instead at duplicate Kindle documents, cloud synchronization, download state or cached thumbnails. Delete the older library copy before sending a repaired file again.

Repair the declarations without editing XML

FixMyEPUB checks both metadata styles and verifies the rebuilt copy before download.

Fix my EPUB cover

Sources