O epubcheck é o validador de conformidade canônico do EPUB, mantido pelo DAISY Consortium e pela comunidade do W3C. Ele lê seu arquivo contra a especificação EPUB e reporta cada desvio como um ERROR ou um WARNING, cada um etiquetado com um código curto como RSC-005. Os códigos parecem crípticos, mas quase todos são mecânicos: um arquivo que falta, um atributo no lugar errado ou um recurso que não deveria estar ali.
Este guia percorre as famílias de erro que você realmente vai encontrar, o que causa cada uma e sua correção típica. A regra de ouro: resolva primeiro cada linha de ERROR — os erros quebram a conformidade e podem impedir que os leitores abram o livro — e depois trabalhe as linhas de WARNING. A Origami usa o mesmo motor do epubcheck, explica cada achado em linguagem simples e coloca os bloqueadores no topo para que você saiba exatamente o que mexer primeiro.
Erros de esquema: RSC-005
O RSC-005 é o erro mais comum e o que mais assusta. Significa que um arquivo falhou na validação de esquema contra a spec — o XML está bem formado, mas algo nele não é permitido onde você o colocou. Causas frequentes: um atributo que não corresponde a um elemento, um elemento aninhado dentro de outro que não pode contê-lo, um valor fora da lista permitida ou uma propriedade indevida em um itemref do spine.
O texto depois do código é a instrução real — leia-o literalmente. Uma mensagem como “attribute X not allowed here” diz com precisão qual atributo remover ou mover. As correções quase sempre são locais: apague o atributo problemático, reaninhe o elemento ou corrija o valor. Corrija um, execute de novo, e um número surpreendente de linhas RSC-005 costuma se reduzir a uma única causa repetida entre os capítulos.
Recursos que faltam e recursos remotos
O RSC-007 e o RSC-001 significam que o epubcheck seguiu uma referência — uma folha de estilos, imagem, fonte ou uma entrada do spine — e não encontrou o destino dentro do contêiner. A causa quase sempre é uma divergência de caminho ou de maiúsculas: um href aponta para images/Cover.jpg mas o arquivo é images/cover.jpg, ou um arquivo foi renomeado e sua referência não. Os caminhos de EPUB diferenciam maiúsculas; corrija o caminho ou restaure o arquivo que falta.
O RSC-006 marca um recurso remoto — uma URL que aponta para fora do EPUB. A spec só permite referências remotas para um conjunto reduzido de mídias, como áudio e vídeo; todo o resto, incluídas imagens, fontes e folhas de estilo, deve ir empacotado dentro do contêiner. A correção é baixar o recurso, adicioná-lo ao manifest e reapontar a referência para a cópia local.
O documento de pacote: erros OPF
Os erros OPF-* vêm do documento de pacote .opf — o manifest, os metadados e o spine. Os mais frequentes: um arquivo que existe no contêiner mas não está declarado no manifest (ou está declarado mas falta), um spine que referencia um id sem item correspondente no manifest, ou metadados Dublin Core obrigatórios ausentes ou mal formados, como um dc:identifier, dc:title ou dc:language faltante.
Trate o OPF como a fonte da verdade: cada arquivo de conteúdo deve aparecer uma vez no manifest com o media type correto, e cada itemref do spine deve apontar para um id de manifest existente. Adicione a declaração que falta, corrija o media type ou forneça o valor de metadado obrigatório, e a cascata de erros derivados costuma se resolver com isso.
Marcação, navegação e empacotamento
Os erros HTM-* significam que o próprio XHTML está mal formado ou usa algo que a spec não permite — uma tag sem fechar, um namespace não declarado ou uma construção obsoleta. Como o conteúdo EPUB é XHTML, deve ser XML bem formado: cada tag fechada, cada atributo entre aspas. Os erros de NCX e navegação apontam para o sumário — um link quebrado no documento nav, ou um descompasso entre o nav e a ordem do spine.
Os erros PKG-* têm a ver com como o ZIP é montado. O clássico: o arquivo mimetype deve ser a primeira entrada do arquivo e estar guardado sem compressão, sem bytes extras. Se sua ferramenta de compressão o comprimiu ou reordenou as entradas, o epubcheck reclama antes mesmo de ler o conteúdo. Reempacote com o mimetype primeiro e sem compressão — a maioria das ferramentas de exportação de EPUB faz isso sozinha, então isso costuma significar evitar um re-zip manual.
A solução, passo a passo
-
1
Valide e leia o relatório em bruto
Passe seu EPUB pelo epubcheck 5.x e capture a saída completa. Cada linha traz um código, uma severidade e uma localização de arquivo e linha — esse trio é o seu mapa até o ponto exato que precisa ser alterado. Não adivinhe; o relatório já nomeia o arquivo.
-
2
Ordene por severidade, primeiro os bloqueadores
Separe os erros dos warnings. Os erros quebram a conformidade e podem impedir que os leitores abram o livro, então resolva cada um antes de tocar em um único warning. Os warnings são de aviso e podem esperar até que os erros desapareçam.
-
3
Corrija por família, do contêiner para dentro
Agrupe os achados — esquema, recursos, documento de pacote, marcação — e comece pelo contêiner: primeiro mimetype e empacotamento, depois o OPF, e por fim os arquivos de conteúdo. Corrigir uma causa raiz costuma resolver várias linhas de uma vez.
-
4
Valide de novo até o relatório ficar limpo
Execute o epubcheck de novo após cada rodada de correções. Os códigos se encadeiam, então uma correção pode resolver ou revelar outras. Repita até não restar nenhum erro, e então decida quais warnings vale a pena limpar para seus leitores.
Os códigos de erro, um por um
Cada bloco abaixo tem as mesmas cinco partes: a linha que o epubcheck realmente imprime, o que significa, por que acontece, a correção e o erro com que mais se confunde. Vá direto a um código, ou procure nesta página a frase que você colou do seu relatório.
RSC-005 — Erro ao fazer o parsing do arquivo
O que o epubcheck imprime:
Error while parsing file: %1$s
- O que significa
- O arquivo é XML bem formado, mas quebrou uma regra do esquema EPUB: algo não é permitido onde você colocou. Tudo o que vem depois dos dois pontos é o texto do próprio validador de esquema, citado tal qual pelo epubcheck.
- Por que acontece
- Um atributo que não pertence àquele elemento, um elemento aninhado dentro de outro que não pode contê-lo, um valor fora da lista permitida, ou uma propriedade solta em um itemref do spine.
- A correção
- Leia a mensagem literalmente: ela nomeia o atributo ou o elemento culpado. Apague, reaninhe ou corrija o valor, e valide de novo. Dezenas de linhas RSC-005 costumam se reduzir a um erro de template repetido em todos os capítulos.
- Quando não é isto
- Como o epubcheck cita aqui o texto bruto do validador de esquema, a mensagem que você está vendo pode não trazer código nenhum. Se você colou uma frase do seu relatório e não a encontra em lugar algum desta página, é quase certo que seja uma mensagem de esquema aninhada dentro de RSC-005 — comece por aqui em vez de caçar um código que não existe.
RSC-007 — O recurso referenciado não foi encontrado no EPUB
O que o epubcheck imprime:
Referenced resource "%1$s" could not be found in the EPUB.
- O que significa
- O epubcheck seguiu uma referência — uma imagem, uma folha de estilos, uma fonte, uma entrada do spine — e o destino não está dentro do contêiner.
- Por que acontece
- Quase sempre uma diferença de caminho ou de maiúsculas: um href aponta para images/Cover.jpg enquanto o arquivo é images/cover.jpg, ou um arquivo foi renomeado e suas referências não.
- A correção
- Faça a referência bater exatamente com o nome e a pasta reais. Os caminhos de EPUB diferenciam maiúsculas e são resolvidos em relação ao arquivo que os contém, não à raiz do livro. Depois, valide de novo.
- Quando não é isto
- Se o arquivo está no contêiner e o epubcheck ainda reclama, o problema é de declaração e não de localização: isso é RSC-008, ou o mesmo fato visto do lado do pacote, que é OPF-003.
RSC-008 — O recurso referenciado não está declarado no manifesto OPF
O que o epubcheck imprime:
Referenced resource "%1$s" is not declared in the OPF manifest.
- O que significa
- O arquivo existe e o caminho resolve, mas o documento de pacote nunca o declara. Para um leitor, um recurso não declarado não existe.
- Por que acontece
- Um recurso adicionado à mão depois da exportação — uma fonte, uma imagem de última hora, uma folha de estilos jogada na pasta sem que ninguém tocasse no OPF.
- A correção
- Adicione um item ao manifesto com um id único, o href relativo à pasta do próprio OPF e o media-type correto. Se o recurso é referenciado a partir do spine, adicione também o itemref correspondente.
- Quando não é isto
- RSC-007 significa que a referência não tem arquivo. Isto significa que o arquivo não tem declaração. Parecem iguais no relatório e têm correções opostas.
RSC-001 — O arquivo não foi encontrado
O que o epubcheck imprime:
File "%1$s" could not be found.
- O que significa
- Um caminho nomeado na estrutura do pacote não resolve para nada dentro do contêiner.
- Por que acontece
- Uma entrada que nunca entrou no ZIP, ou um caminho em META-INF/container.xml ou no OPF que aponta para onde o arquivo não está.
- A correção
- Confira se o container.xml nomeia o .opf real, e depois se cada href do manifesto resolve em relação à pasta onde o OPF vive. Reempacote quando os caminhos concordarem.
- Quando não é isto
- RSC-007 é uma referência quebrada de dentro do seu conteúdo. RSC-001 costuma ser um caminho quebrado no empacotamento em volta, então olhe o contêiner antes de abrir um capítulo.
RSC-006 — Referência a recurso remoto não é permitida neste contexto
O que o epubcheck imprime:
Remote resource reference is not allowed in this context; resource "%1$s" must be located in the EPUB container.
- O que significa
- Algo que o leitor precisa baixar para renderizar a página vive em uma URL fora do livro. A especificação só permite referências remotas para um conjunto restrito de mídias, como áudio e vídeo.
- Por que acontece
- Uma webfont hospedada, uma imagem ainda apontando para um CDN, ou um include de folha de estilos que sobreviveu de um template HTML.
- A correção
- Baixe o recurso, adicione-o ao manifesto e reaponte a referência para a cópia local. Um livro que depende de um servidor é um livro que para de funcionar sem conexão.
- Quando não é isto
- Um hiperlink no seu texto para um site externo está certo e não é o que se reporta aqui. A regra é sobre recursos necessários para renderizar, não sobre destinos que o leitor pode escolher visitar.
OPF-003 — O item existe no EPUB, mas não está declarado no manifesto OPF
O que o epubcheck imprime:
Item "%1$s" exists in the EPUB, but is not declared in the OPF manifest.
- O que significa
- O mesmo fato de RSC-008, reportado do lado do pacote: há um arquivo no contêiner que o manifesto nunca menciona.
- Por que acontece
- Sobras, na maioria das vezes — uma capa não usada, o backup de um editor, fontes de um design substituído, metadados do sistema operacional que entraram no ZIP.
- A correção
- Declare-o se o livro precisa dele; apague-o do contêiner se não. Um arquivo não declarado é distribuído do mesmo jeito e custa ao seu leitor o download.
- Quando não é isto
- RSC-007 é uma referência sem arquivo. Isto é um arquivo sem referência. O relatório se lê quase igual; as correções vão em direções opostas.
OPF-014 — A propriedade deveria estar declarada no arquivo OPF
O que o epubcheck imprime:
The property "%1$s" should be declared in the OPF file.
- O que significa
- Um documento de conteúdo usa um recurso — scripting, MathML, SVG, um recurso remoto — que o seu item no manifesto deveria anunciar pelo atributo properties, e não anuncia.
- Por que acontece
- Uma capa em SVG ou um elemento svg em linha adicionado depois da exportação, MathML colado de outra fonte, ou um script somado para uma figura interativa.
- A correção
- Adicione ao atributo properties daquele item a propriedade que o epubcheck nomeia. Várias propriedades num mesmo item são separadas por espaços.
- Quando não é isto
- OPF-015 é a imagem espelhada: uma propriedade declarada para um recurso que o arquivo não usa. Adicionar propriedades «por via das dúvidas» troca este erro por aquele.
OPF-030 — O unique-identifier não foi encontrado
O que o epubcheck imprime:
The unique-identifier "%1$s" was not found.
- O que significa
- O atributo unique-identifier do elemento package aponta para o id de um dc:identifier, e não existe nenhum elemento com esse id.
- Por que acontece
- O identificador foi reescrito — um ISBN novo, um UUID regenerado — e o seu atributo id foi apagado ou renomeado enquanto o atributo do package continuou apontando para o nome antigo.
- A correção
- Dê um id ao dc:identifier e faça o unique-identifier no elemento package nomear exatamente esse id. As duas strings precisam bater caractere por caractere.
- Quando não é isto
- Isto é sobre o ponteiro, não sobre o valor. Um livro com um ISBN perfeitamente válido falha aqui do mesmo jeito se nada aponta para ele, então não procure um problema no identificador em si.
PKG-006 — A entrada mimetype está ausente ou não é o primeiro arquivo do pacote
O que o epubcheck imprime:
Mimetype file entry is missing or is not the first file in the archive.
- O que significa
- O ZIP está montado errado. O epubcheck chega aqui antes de ler uma única linha do seu conteúdo, e é por isso que o resto do relatório pode parecer estranhamente curto.
- Por que acontece
- Um re-zip à mão, ou feito pelo compactador do sistema operacional, que ordena as entradas em ordem alfabética e coloca META-INF primeiro.
- A correção
- Remonte o pacote com a entrada mimetype adicionada primeiro e guardada sem compressão, e só então todo o resto. A maioria das ferramentas de exportação EPUB já faz isso — a correção costuma ser parar de recompactar a pasta manualmente.
- Quando não é isto
- Nada disto é um problema de conteúdo. Não procure no seu XHTML: nenhuma edição dentro do livro vai limpar esta linha.
PKG-007 — O arquivo mimetype só deveria conter a string e não estar comprimido
O que o epubcheck imprime:
Mimetype file should only contain the string "application/epub+zip" and should not be compressed.
- O que significa
- A entrada mimetype está no lugar certo, mas o seu conteúdo ou a forma como foi guardada estão errados.
- Por que acontece
- Um editor de texto que acrescentou uma quebra de linha ou uma marca BOM, ou uma etapa de compressão que comprimiu a entrada junto com todo o resto.
- A correção
- Escreva exatamente os vinte caracteres application/epub+zip — sem quebra de linha final, sem BOM — e adicione a entrada ao pacote armazenada, não deflacionada.
- Quando não é isto
- PKG-006 é sobre onde a entrada está; isto é sobre o que há nela e como foi guardada. Corrigir um e validar de novo costuma só fazer aparecer o outro.
HTM-004 — DOCTYPE irregular
O que o epubcheck imprime:
Irregular DOCTYPE: found "%1$s", expected "%2$s".
- O que significa
- Um documento de conteúdo carrega uma declaração de doctype que o EPUB 3 não espera.
- Por que acontece
- Um doctype de XHTML 1.1 ou de EPUB 2 que sobreviveu a uma conversão, ou um doctype com um subconjunto interno para que o arquivo possa usar entidades HTML nomeadas.
- A correção
- Substitua a declaração inteira por <!DOCTYPE html>. Se o arquivo dependia de entidades nomeadas, troque-as por referências numéricas ou pelos caracteres literais — um subconjunto interno não é o jeito de mantê-las.
- Quando não é isto
- Isto não é sobre a declaração XML da primeira linha. Ela é outra coisa, é permitida, e removê-la não vai limpar este erro.
NCX-001 — O identificador do NCX não coincide com o do OPF
O que o epubcheck imprime:
NCX identifier ("%1$s") does not match OPF identifier ("%2$s").
- O que significa
- A tabela de conteúdo NCX herdada carrega um valor dtb:uid que não coincide com o dc:identifier do documento de pacote.
- Por que acontece
- O identificador do OPF foi regenerado — um ISBN novo para uma edição nova, um UUID fresco de uma exportação — e o NCX ficou com o antigo.
- A correção
- Copie o valor do dc:identifier do OPF para dentro do <meta name="dtb:uid"> do NCX. Se você não dá mais suporte a leitores EPUB 2, remover o NCX por completo também é uma resposta válida.
- Quando não é isto
- Isto não significa que a sua tabela de conteúdo está quebrada. A navegação do EPUB 3 vive no documento nav; o NCX é a cópia de compatibilidade ao lado dele, e aqui só o seu identificador está em questão.