{"record":{"id":"09ce71aec34b04bc","repo":"Kareadita/Kavita","slug":"there-was-an-error-when-extracting-archivepath","errorCode":null,"errorMessage":"There was an error when extracting {archivePath}. Check the file exists, has read permissions or the server OS can support all path characters.","messagePattern":"There was an error when extracting (.+?)\\. Check the file exists, has read permissions or the server OS can support all path characters\\.","errorType":"exception","errorClass":"KavitaException","httpStatus":null,"severity":"error","filePath":"Kavita.Services/ArchiveService.cs","lineNumber":564,"sourceCode":"                                                                          && !Parser.HasBlacklistedFolderInPath(Path.GetDirectoryName(entry.Key) ?? string.Empty)\n                                                                          && Parser.IsImage(entry.Key)), extractPath);\n                    break;\n                }\n                case ArchiveLibrary.NotSupported:\n                    logger.LogWarning(\"[ExtractArchive] This archive cannot be read: {ArchivePath}\", archivePath);\n                    return;\n                default:\n                    logger.LogWarning(\"[ExtractArchive] There was an exception when reading archive stream: {ArchivePath}\", archivePath);\n                    return;\n            }\n\n        }\n        catch (Exception ex)\n        {\n            logger.LogWarning(ex, \"[ExtractArchive] There was a problem extracting {ArchivePath} to {ExtractPath}\",archivePath, extractPath);\n            mediaErrorService.ReportMediaIssue(archivePath, MediaErrorProducer.ArchiveService,\n                \"This archive cannot be read or not supported\", ex);\n            throw new KavitaException(\n                $\"There was an error when extracting {archivePath}. Check the file exists, has read permissions or the server OS can support all path characters.\");\n        }\n        logger.LogDebug(\"Extracted archive to {ExtractPath} in {ElapsedMilliseconds} milliseconds\", extractPath, sw.ElapsedMilliseconds);\n    }\n}\n","sourceCodeStart":546,"sourceCodeEnd":570,"githubUrl":"https://github.com/Kareadita/Kavita/blob/9c3e5400007f8a0282f7d883f2ad5e71716e514d/Kavita.Services/ArchiveService.cs#L546-L570","documentation":"Catch-all thrown by ArchiveService.ExtractArchive (line 564) for any exception during extraction that is not the NotSupported/default early-return. The archive is opened via ZipFile.OpenRead or SharpCompress ArchiveFactory; if either throws (corrupt zip, unsupported compression, path-too-long on extraction, IO error), the original exception is logged AND reported via mediaErrorService.ReportMediaIssue, then re-thrown as this KavitaException. The message is interpolated with the archive path.","triggerScenarios":"Reading/caching an archive (CBZ/CBR/ZIP) that is corrupt, truncated, uses an unsupported codec, or contains entries with path characters the OS rejects (e.g. ':' on Windows, > 260 chars). Triggered during library scan/cache extraction.","commonSituations":"Partially downloaded/truncated manga archive; RAR5 requiring SharpCompress fallback; Windows path-length limit (MAX_PATH) hit by deeply nested entries; permission denied reading the file.","solutions":["Re-download or repair the offending archive (the archive path is in the message and the MediaError log).","On Windows, enable long-path support and ensure the cache directory path is short.","Confirm the process has read permission on the archive; check mediaErrorService records for recurring offenders.","If a specific codec is unsupported, re-save the archive as standard ZIP/CBZ."],"exampleFix":"// before\ncatch (Exception ex) {\n    logger.LogWarning(ex, \"[ExtractArchive] There was a problem extracting {ArchivePath} to {ExtractPath}\", archivePath, extractPath);\n    mediaErrorService.ReportMediaIssue(archivePath, MediaErrorProducer.ArchiveService, \"This archive cannot be read or not supported\", ex);\n    throw new KavitaException($\"There was an error when extracting {archivePath}. Check the file exists, has read permissions or the server OS can support all path characters.\");\n}\n\n// caller — skip known-bad archives instead of crashing the scan\nif (!archiveService.IsValidArchive(path)) continue;","handlingStrategy":"try-catch","validationCode":"// Skip archives that fail validity before extracting\nif (!archiveService.IsValidArchive(path)) continue;","typeGuard":null,"tryCatchPattern":"catch (KavitaException ex) { /* Extraction failed; report/skip this archive */ logger.LogWarning(ex.Message); }\n// The service already reports via mediaErrorService — surface those records to the user.","preventionTips":["Keep archives intact (avoid truncated/partial downloads).","On Windows, enable long paths and keep the cache directory path short.","Monitor mediaErrorService records to find and repair recurring bad archives."],"tags":["archive","extraction","io-error","corrupt-file","catch-all"],"backgroundTag":null,"analyzedSha":"9c3e5400007f8a0282f7d883f2ad5e71716e514d","analyzedAt":"2026-08-13T19:06:05.897Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}