Kareadita/Kavita · error · KavitaException

There was an error when extracting {archivePath}. Check the

Error message

There was an error when extracting {archivePath}. Check the file exists, has read permissions or the server OS can support all path characters.

What it means

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.

Source

Thrown at Kavita.Services/ArchiveService.cs:564

                                                                          && !Parser.HasBlacklistedFolderInPath(Path.GetDirectoryName(entry.Key) ?? string.Empty)
                                                                          && Parser.IsImage(entry.Key)), extractPath);
                    break;
                }
                case ArchiveLibrary.NotSupported:
                    logger.LogWarning("[ExtractArchive] This archive cannot be read: {ArchivePath}", archivePath);
                    return;
                default:
                    logger.LogWarning("[ExtractArchive] There was an exception when reading archive stream: {ArchivePath}", archivePath);
                    return;
            }

        }
        catch (Exception ex)
        {
            logger.LogWarning(ex, "[ExtractArchive] There was a problem extracting {ArchivePath} to {ExtractPath}",archivePath, extractPath);
            mediaErrorService.ReportMediaIssue(archivePath, MediaErrorProducer.ArchiveService,
                "This archive cannot be read or not supported", ex);
            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.");
        }
        logger.LogDebug("Extracted archive to {ExtractPath} in {ElapsedMilliseconds} milliseconds", extractPath, sw.ElapsedMilliseconds);
    }
}

View on GitHub (pinned to 9c3e540000)

Solutions

  1. Re-download or repair the offending archive (the archive path is in the message and the MediaError log).
  2. On Windows, enable long-path support and ensure the cache directory path is short.
  3. Confirm the process has read permission on the archive; check mediaErrorService records for recurring offenders.
  4. If a specific codec is unsupported, re-save the archive as standard ZIP/CBZ.

Example fix

// before
catch (Exception ex) {
    logger.LogWarning(ex, "[ExtractArchive] There was a problem extracting {ArchivePath} to {ExtractPath}", archivePath, extractPath);
    mediaErrorService.ReportMediaIssue(archivePath, MediaErrorProducer.ArchiveService, "This archive cannot be read or not supported", ex);
    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.");
}

// caller — skip known-bad archives instead of crashing the scan
if (!archiveService.IsValidArchive(path)) continue;
Defensive patterns

Strategy: try-catch

Validate before calling

// Skip archives that fail validity before extracting
if (!archiveService.IsValidArchive(path)) continue;

Try / catch

catch (KavitaException ex) { /* Extraction failed; report/skip this archive */ logger.LogWarning(ex.Message); }
// The service already reports via mediaErrorService — surface those records to the user.

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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