Ebook nie przechodzi walidacji EPUBCheck – najczęstsze błędy i jak je naprawić

EPUBCheck to bramka, przez którą musi przejść każdy plik trafiający do sprzedaży – dystrybutorzy walidują nim ebooki na wejściu i odrzucają te z błędami. Dobra wiadomość: komunikaty EPUBCheck, choć wyglądają groźnie, układają się w kilka powtarzalnych kategorii. Poniżej najczęstsze błędy, ich prawdziwe przyczyny i sposoby naprawy.

Jak w ogóle uruchomić EPUBCheck?

Trzy drogi, od najprostszej:

Plugin do edytora Sigil (wrapper EPUBCheck) – walidacja jednym kliknięciem podczas pracy nad plikiem;
Wersja CLI – java -jar epubcheck.jar ksiazka.epub; wymaga Javy, za to waliduje się partiami i automatyzuje;
Walidatory online – dla pojedynczego szybkiego sprawdzenia (uwaga na wysyłanie plików objętych umowami na zewnętrzne serwery).

Zawsze używaj możliwie najnowszej wersji – starsze przepuszczają błędy, które dystrybutor z nowszą wersją już wyłapie. I czytaj wynik od góry: jeden błąd źródłowy (np. niedomknięty tag) potrafi wygenerować lawinę wtórnych komunikatów.

Błędy struktury dokumentu (RSC-005 i rodzina)

RSC-005: Error while parsing file – najczęstszy komunikat świata EPUB. To zbiorcza informacja „ten XHTML jest niepoprawny", a szczegół tkwi w dopisku:

element X not allowed here – element w złym miejscu, np. <p> wewnątrz <span>, listy zagnieżdżone bez <li>, tekst luzem w <body>. Naprawa: poprawna hierarchia HTML.
niedomknięte lub skrzyżowane tagi – częsta pamiątka po ręcznych poprawkach w kodzie. Naprawa: domknięcie struktury; funkcje typu „napraw i uporządkuj kod" w edytorze EPUB załatwiają większość przypadków.
surowe znaki &, < w treści – w XHTML muszą być zapisane jako encje (&, <).
duplicate ID – powtórzony identyfikator, zwykle po kopiowaniu przypisów lub rozdziałów. Naprawa: unikalne id w całym pliku.

Błędy manifestu i plików (OPF-, RSC-001/007, PKG-)

Manifest w pliku OPF to spis wszystkiego, co jest w środku ebooka – i wszystko musi się zgadzać w obie strony:

RSC-001 / RSC-007: referenced resource ... could not be found – plik wskazany w manifeście nie istnieje albo link prowadzi donikąd. Klasyka po zmianie nazw ilustracji bez aktualizacji odwołań. (Na marginesie: nazwy plików graficznych ze spacjami i polskimi znakami to proszenie się o tę kategorię błędów – krótkie img001.jpg oszczędza kłopotów.)
OPF-003: item exists ... but is not declared in the OPF – plik-sierota w paczce; usuwamy go albo deklarujemy.
OPF-014: property "X" should be declared – np. plik zawiera SVG lub skrypty, a manifest o tym nie mówi; dodaje się właściwość do wpisu w manifeście.
PKG-... – problemy z samą paczką ZIP: zła kolejność (mimetype musi być pierwszy, bez kompresji), śmieciowe pliki systemowe. Naprawa: ponowne spakowanie narzędziem do EPUB, nie systemowym ZIP-em.

Błędy nawigacji (NAV-, NCX-)

NCX-001: identifier does not match – identyfikator książki w NCX różni się od OPF; częste po podmianie ISBN.
spis treści wskazujący nieistniejące pliki – pamiątka po usuwaniu rozdziałów. O nawigacji piszemy szerzej w artykule spis treści nie działa w ebooku.
brak wymaganych elementów nav – EPUB 3 wymaga dokumentu nawigacyjnego z epub:type="toc"; eksporty z niektórych narzędzi potrafią go okaleczyć.

Błędy metadanych (OPF-025…, RSC-005 w OPF)

brak wymaganych pól: dc:title, dc:identifier, dc:language, dcterms:modified (to ostatnie w formacie 2026-07-02T12:00:00Z – literówka w dacie to walidacyjny klasyk);
zły format identyfikatora (ISBN z błędem, UUID bez prefiksu urn:uuid:).

Kompletne, poprawne metadane to zresztą więcej niż walidacja – to też metadane dostępności wymagane przez EAA, których EPUBCheck jeszcze nie wymusza, a dystrybutorzy coraz częściej tak.

„EPUBCheck przechodzi, ale…" – czego walidator NIE sprawdza

Zero błędów w EPUBCheck nie oznacza dobrego ebooka. Walidator potwierdza poprawność techniczną paczki – nie sprawdzi, czy:

kolejność czytania ma sens,
nagłówki odpowiadają strukturze książki,
alt-teksty istnieją i coś wnoszą,
plik spełnia wymogi dostępności (od tego jest Ace by DAISY),
książka w ogóle dobrze wygląda na czytniku (osobny temat).

Dlatego rzetelna kontrola to zawsze: EPUBCheck + Ace + przegląd manualny + test na czytniku. Plik oddaje się dopiero wtedy, gdy wszystkie cztery są czyste.

Kiedy naprawiać samodzielnie, a kiedy oddać specjaliście?

Pojedynczy błąd z czytelnym komunikatem – śmiało, do samodzielnej naprawy. Sygnały, że taniej będzie oddać plik w ręce konwertera:

dziesiątki błędów różnych kategorii – to zwykle objaw złego eksportu u źródła; łatanie pojedynczo trwa dłużej niż porządna przebudowa,
plik po wielu rękach – poprawki na poprawkach, mieszanka konwencji,
deadline dystrybucyjny – naprawa + pełna walidacja + test to nasz standard w usłudze poprawiania istniejących ebooków.

FAQ

Czym różni się błąd (ERROR) od ostrzeżenia (WARNING)? Błędy blokują – dystrybutorzy odrzucają pliki z błędami. Ostrzeżenia warto przejrzeć, ale nie zawsze wymagają działania. Do sprzedaży: zero błędów, ostrzeżenia świadomie ocenione.

Dystrybutor odrzucił plik, choć u mnie EPUBCheck przechodzi. Jak to możliwe? Najpewniej różnica wersji EPUBCheck albo dodatkowe, własne reguły platformy – o tym piszemy w artykule ebook odrzucony przez dystrybutora.

Czy EPUBCheck sprawdza dostępność (EAA)? Nie – od tego jest Ace by DAISY. EPUBCheck = poprawność techniczna, Ace = dostępność. Potrzebne są oba.

Plik sypie błędami, a termin goni? Naprawiamy źle przygotowane ebooki – walidacja EPUBCheck + Ace w standardzie. Wycena w 24 h → Zanim zlecisz naprawę, sprawdź plik sam – darmowy checker EPUB pokaże metadane, spis treści i test dostępności bez wysyłania pliku.