{"record":{"id":"5a5106186b64ab52","repo":"Kareadita/Kavita","slug":"image-file-not-found-in-epub-imagekey","errorCode":null,"errorMessage":"Image file not found in epub: {imageKey}","messagePattern":"Image file not found in epub: (.+?)","errorType":"exception","errorClass":"KavitaException","httpStatus":null,"severity":"warning","filePath":"Kavita.Services/BookService.cs","lineNumber":1286,"sourceCode":"                throw new KavitaException(\"Image element does not have a valid source attribute\");\n            }\n\n            var imageSource = targetImage.Attributes[srcAttributeName].Value;\n\n            // Clean and get the correct key for the image\n            var imageKey = CleanContentKeys(GetKeyForImage(book, imageSource));\n\n            // Check if it's an external URL\n            if (imageKey.StartsWith(\"http\"))\n            {\n                throw new KavitaException(\"Cannot copy external images\");\n            }\n\n            // Get the image file from the epub\n\n            if (!book.Content.Images.TryGetLocalFileRefByKey(imageKey, out var imageFile))\n            {\n                throw new KavitaException($\"Image file not found in epub: {imageKey}\");\n            }\n\n            // Read the image content\n            var imageContent = await imageFile.ReadContentAsBytesAsync();\n\n            // Determine file extension from the image key or content type\n            var extension = Path.GetExtension(imageKey);\n            if (string.IsNullOrEmpty(extension))\n            {\n                // Fallback to determining extension from content type\n                extension = imageFile.ContentType switch\n                {\n                    EpubContentType.IMAGE_JPEG => \".jpg\",\n                    EpubContentType.IMAGE_PNG => \".png\",\n                    EpubContentType.IMAGE_GIF => \".gif\",\n                    EpubContentType.IMAGE_SVG => \".svg\",\n                    _ => \".png\"\n                };","sourceCodeStart":1268,"sourceCodeEnd":1304,"githubUrl":"https://github.com/Kareadita/Kavita/blob/9c3e5400007f8a0282f7d883f2ad5e71716e514d/Kavita.Services/BookService.cs#L1268-L1304","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Repair the epub so the manifest contains the referenced image at the matching (case-correct) key.","Audit CleanContentKeys/GetKeyForImage to ensure src URLs (URL-encoded, fragment-stripped) normalize to manifest keys.","Run an epub validator (epubcheck) on the offending book."],"exampleFix":"// before\nif (!book.Content.Images.TryGetLocalFileRefByKey(imageKey, out var imageFile))\n    throw new KavitaException($\"Image file not found in epub: {imageKey}\");\n\n// diagnostic — log all available keys to spot case/encoding mismatch\nvar keys = book.Content.Images.Select(i => i.Key);\nlogger.LogDebug(\"Image keys: {Keys}\", string.Join(\", \", keys));","handlingStrategy":"validation","validationCode":"// Diagnostic: list manifest image keys to compare against the src-derived key\nvar keys = book.Content.Images.Select(i => i.Key).ToList();\nif (!keys.Contains(imageKey, StringComparer.OrdinalIgnoreCase)) { /* repair needed */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate epubs with epubcheck before import.","Ensure CleanContentKeys/GetKeyForImage normalize encoded/case-variant src to manifest keys.","Re-export epubs whose image files were dropped but still referenced."],"tags":["book-reader","epub","bookmark","corrupt-file","data-not-found"],"backgroundTag":null,"analyzedSha":"9c3e5400007f8a0282f7d883f2ad5e71716e514d","analyzedAt":"2026-08-13T19:06:05.897Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}