# EPUBCheck MED_012: media-overlay id mismatch, how to fix it

Source: https://epubcc.com/epubcheck/med_012/ (updated 2026-11-04)

EPUBCheck MED_012 is an error message: “The "media-overlay" attribute does not match the ID of the Media Overlay that refers to this document.” The media-overlay attribute of a chapter names a different overlay from the one that refers to it. The SMIL file that narrates a chapter and the chapter's manifest item must point at each other.

- Official message (EPUBCheck 5.4.0): The "media-overlay" attribute does not match the ID of the Media Overlay that refers to this document.
- Default severity: Error

## Typical causes

- Overlay ids renamed or swapped in the manifest.
- A chapter copied with its manifest item, keeping the original's media-overlay value.

## How to fix it

1. Find the SMIL file whose text elements point to the chapter EPUBCheck names.
2. Set the chapter's media-overlay attribute to the manifest id of that SMIL file.
3. Check the other chapters the same way: these errors usually come in groups.
4. Rebuild the EPUB and run EPUBCheck again to confirm the message is gone.

## When it's not this

If the attribute is missing altogether, the error is MED_010.

## Sources

- EPUB 3.3, §9.3.5.1 Including media overlays: https://www.w3.org/TR/epub-33/#sec-package-including (read 2026-11-04)

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