Surface details of metadata issues

[sargunv]

Idea Description

I'm facing similar issues as #1921; lots of "There was an exception parsing metadata" or "There was an exception when opening epub book" or errors counting words, etc. And I understand the issues are likely in the epub and pdf files themselves.

But it would be nice if the app surfaced some details about exactly what the exception is so I can debug and fix the files.

If I search the logs, I do get a bit more info, but even there it's vague for example:

[Kavita] [2025-10-29 15:15:07.811 -07:00  57] [Error] API.Services.Tasks.Metadata.WordCountAnalyzerService There was an error reading an epub file for word count, series skipped
System.IO.InvalidDataException: A local file header is corrupt.

The obvious question when seeing that log: which epub file? Which ZipArchiveEntry within the epub zip?

App screenshot

Log screenshot

Idea Category

User Experience

Duration of Using Kavita

1 day

Before submitting

• I've already searched for existing ideas before posting.

[scare376]

@majora2007 can correct me if im wrong but its done that way because the details do not matter that much. there are other errors involving items that do give more details but most of the solutions are all the same. For epub you process the book in calibre, that may mean using polish to upgrade the internals to epub 3 (fixes a lot of issues) or doing an epub to epub conversion so calibre rebuilds the book. For CBZ it means you need to unpack it, check for corruption, and repack it. PDF ill be honest ive not come across one of those errors but it likely just needs the metadata reset with calibre.

[sargunv]

About a third of these affected files were already processed or built with calibre.

And even if calibre could fix them entirely, knowing the details of the errors will help me understand common themes in where the broken files are coming from, or report issues to the publisher if the issues originated on their end.

[scare376]

Also we do have https://wiki.kavitareader.com/troubleshooting/media-errors/ which does try to explain what the errors mean. like the error you got means that kavita was unable to open the file in order to read the contents. Other apps might have a lot of hacks to open bad files but kavita does not.

[sargunv]

"unable to open the file" is pretty vague. The log is a bit better, telling me the header for a particular zip (epub) file entry is corrupted, but doesn't say which epub file or which entry. Both bits of info should be loggable from that point, and would be convenient to also surface in the web ui.

[majora2007]

We actually don't get much information back from the varying libraries we use to open and parse files. As scare376 mentions, there are basically only 2 steps to fix them.

Calibre can open anything, they have a plethora of hacks. The libraries we use don't and as such, these issues happen despite them working in Calibre.

I understand your frustration, but it's the reality of the tooling and not something we could easily surface, especially when the end result is the same.