EPUB error guide
Use this when EPUBCheck says a file does not match its declared media type. The scan compares content.opf with the file path and extension, then shows whether only the manifest needs to change.
Your error
The file exists, but content.opf describes it as a different type, such as a PNG image declared as image/jpeg.
What the scan checks
The report compares the packaged path, file extension, declared media-type, and EPUBCheck message before suggesting a change.
Stop if
Do not change the manifest when the asset itself needs to be restored, replaced, or exported again.
Scan the EPUB to check file paths and see what can be repaired or needs manual review. Your original EPUB stays unchanged.
Need fixed-layout, DRM, or source-file help? Check unsupported or review-first EPUB cases.
Match these report titles
Start here
OPF_029 means EPUBCheck found that the file and its content.opf media type do not agree. Verify the file before editing the manifest.
The EPUB package points to a real file, but content.opf describes that file as the wrong resource type. Kindle and EPUBCheck use the OPF manifest to understand whether a file is an image, stylesheet, XHTML document, SVG, font, or another packaged asset.
A repair is possible when the file exists, the href is correct, and the file format has been verified. The change updates only the manifest media-type and keeps the same file path.
Copy the exact manifest href and declared media-type from content.opf before making any change.
It should stop for manual review when the asset itself may be wrong, missing, duplicated, or part of a broader export problem. The tool should not swap files, rename assets, or guess a replacement format.
1. Example report output
A useful report should connect the manifest item to the referenced file instead of only saying the media type is wrong.
EPUBCheck message
ERROR(OPF-029): OEBPS/content.opf: Item "images/cover.png" does not appear to match the media type image/jpeg.
Plain explanation
The media type in content.opf does not match the file EPUBCheck inspected.
EPUB Fixer report
Manifest href images/cover.png is declared as image/jpeg, but the packaged file extension is .png.
Do this next
Verify the file first. Change the media-type only when the file is correct and the manifest entry is the only mismatch.
Do not do this
Do not rename the file, swap in a new asset, or guess a different format just to clear OPF_029.
A safe fix keeps the same file and updates only the manifest media-type after the file has been verified.
2. Next step
The next step depends on whether the EPUB already contains the right file and only the OPF manifest entry is wrong.
Scan first
Upload the EPUB so the report can show the manifest href, the packaged file path, and the exact media-type mismatch before you edit content.opf.
Safe repair
Update the manifest media-type when the file format is known and the manifest is the only mismatch, then validate again.
Manual review
Stop when the asset may need re-export, replacement, or author or EPUB editor judgment instead of a manifest-only correction.
3. Concrete path example
The report should show the same href in content.opf and the real file it points to inside the EPUB.
EPUBCheck: ERROR(OPF-029): OEBPS/content.opf: Item "images/cover.png" does not appear to match the media type image/jpeg. Report: Manifest href: images/cover.png Declared media-type: image/jpeg Packaged file: OEBPS/images/cover.png File extension: .png Fix decision: verify that the file is a PNG, then update the manifest
If the file itself is wrong or missing, the next step is source repair, not a manifest-only change.
Quick decision
A wrong media-type can be a small package-only fix. It should not turn into renaming files, swapping assets, or guessing the book's intended resource format.
Scan first
Use the scan to connect the manifest href to the real packaged file before changing content.opf.
Safe fix
Update only the manifest media-type, keep the same file path, and validate the EPUB again.
Stop
Do not guess when the asset may be the wrong file, the wrong conversion output, or part of a larger packaging problem.
Common situations
Start with the file path named by the manifest and verify that file before changing anything.
The file exists and the href already points to cover.png, but content.opf still says image/jpeg.
Set media-type to image/png, then validate again.
The asset exists, but the manifest entry does not match the actual image format or file extension.
Update the manifest entry only if the packaged file is the intended asset.
The manifest href points to a real packaged file, but the media-type belongs to another resource category.
Correct the OPF media-type only when the file path and resource type are unambiguous.
The extension, packaged file, and actual resource may no longer agree after a source-tool export or manual ZIP edit.
Re-export or replace the source asset when the file itself is wrong, instead of patching content.opf blindly.
OPF_029: The manifest media type does not match the referenced file.
EPUBCheck, Kindle Previewer, or KDP finds a manifest item in content.opf whose media-type does not match the actual packaged file or file extension.
What it means
Common causes include an image converted from JPG to PNG without updating content.opf, files renamed after export, manual ZIP edits, assets copied between EPUBs, and source tools that leave an old media-type value in the manifest.
Before you edit
Do not change media-type just because the extension looks familiar. First confirm the manifest href, the real file extension, and whether the file was renamed, converted, or exported incorrectly.
Why KDP checks it
The OPF file is the EPUB's map: metadata, file list, reading order, and navigation wiring. KDP and EPUBCheck use it to decide whether the book package is coherent.
EPUBCheck checks EPUB 2 and EPUB 3 files against the official rules and reports package, markup, link, and file-reference problems.
Repair example
Before: content.opf declares images/cover.png as image/jpeg. After: the same manifest item is updated to image/png and the EPUB is validated again. Before: the EPUB contains the wrong exported image file entirely; that should go back to the source project instead of being guessed in place.
Ready to retry?
The report shows the manifest item, packaged path, file extension, declared media-type, and EPUBCheck message so you can decide whether the manifest alone is wrong.
Upload EPUB to scanFAQ
It means content.opf declares a file as one resource type, such as image/jpeg, while the packaged file looks like another type, such as image/png.
Yes, but only when the file format is verified, the path is correct, and the fix is limited to updating the OPF manifest entry. The repaired EPUB still has to pass EPUBCheck again.
Not by default. If the packaged asset is already the intended file, the safer change is usually to fix content.opf. Rename or replace the file only when the source export itself is wrong.
Local readers may still show the image, but EPUBCheck and Kindle use the OPF manifest to validate whether the package inventory describes the file correctly.
