Kareadita/Kavita · warning · KavitaException

Image file not found in epub: {imageKey}

Error message

Image file not found in epub: {imageKey}

What it means

Thrown by BookService.CopyImageToTempFromBook (line 1286) when book.Content.Images.TryGetLocalFileRefByKey(imageKey) returns false — the image src referenced by the XHTML page does not match any image declared in the epub's manifest (the cleaned key has no corresponding entry). Indicates a broken epub: the XHTML references an image the manifest does not provide.

Source

Thrown at Kavita.Services/BookService.cs:1286

                throw new KavitaException("Image element does not have a valid source attribute");
            }

            var imageSource = targetImage.Attributes[srcAttributeName].Value;

            // Clean and get the correct key for the image
            var imageKey = CleanContentKeys(GetKeyForImage(book, imageSource));

            // Check if it's an external URL
            if (imageKey.StartsWith("http"))
            {
                throw new KavitaException("Cannot copy external images");
            }

            // Get the image file from the epub

            if (!book.Content.Images.TryGetLocalFileRefByKey(imageKey, out var imageFile))
            {
                throw new KavitaException($"Image file not found in epub: {imageKey}");
            }

            // Read the image content
            var imageContent = await imageFile.ReadContentAsBytesAsync();

            // Determine file extension from the image key or content type
            var extension = Path.GetExtension(imageKey);
            if (string.IsNullOrEmpty(extension))
            {
                // Fallback to determining extension from content type
                extension = imageFile.ContentType switch
                {
                    EpubContentType.IMAGE_JPEG => ".jpg",
                    EpubContentType.IMAGE_PNG => ".png",
                    EpubContentType.IMAGE_GIF => ".gif",
                    EpubContentType.IMAGE_SVG => ".svg",
                    _ => ".png"
                };

View on GitHub (pinned to 9c3e540000)

Solutions

1. Repair the epub so the manifest contains the referenced image at the matching (case-correct) key.
2. Audit CleanContentKeys/GetKeyForImage to ensure src URLs (URL-encoded, fragment-stripped) normalize to manifest keys.
3. Run an epub validator (epubcheck) on the offending book.

Example fix

// before
if (!book.Content.Images.TryGetLocalFileRefByKey(imageKey, out var imageFile))
    throw new KavitaException($"Image file not found in epub: {imageKey}");

// diagnostic — log all available keys to spot case/encoding mismatch
var keys = book.Content.Images.Select(i => i.Key);
logger.LogDebug("Image keys: {Keys}", string.Join(", ", keys));

// Diagnostic: list manifest image keys to compare against the src-derived key
var keys = book.Content.Images.Select(i => i.Key).ToList();
if (!keys.Contains(imageKey, StringComparer.OrdinalIgnoreCase)) { /* repair needed */ }

When it happens

Trigger: Bookmark/copy-image on an epub where the <img src> points to a file missing from the OEBPS/images manifest (renamed, deleted, or never packaged). CleanContentKeys/GetKeyForImage normalization may also produce a key that doesn't match the manifest entry.

Common situations: Broken conversion/export that dropped an image file but left the reference; case-sensitivity mismatch (image.JPG vs image.jpg) on case-sensitive filesystems; XML-entity-encoded src not normalized by CleanContentKeys.

Related errors

• No images found on the specified page
• Image index {bookmarkDto.ImageOffset} is out of range. Page
• Image element does not have a valid source attribute
• Cannot copy external images
• Page {bookmarkDto.Page} not found in epub

AI-assisted analysis of Kareadita/Kavita@9c3e540000 (2026-08-13). Data as JSON: /api/errors/5a5106186b64ab52. Report an issue: GitHub.