What causes "file-doesnt-exist" in Kareadita/Kavita?

Run a library scan or 'Scan Library' from the UI to sync the database with the actual disk state

Kareadita/Kavita · error · KavitaException

file-doesnt-exist

Error message

file-doesnt-exist

What it means

Thrown during cache extraction when a file tracked in the database no longer exists on disk. The code iterates over files and checks directoryService.FileSystem.Path.Exists(file.FilePath) before extracting; a missing file aborts the entire extraction with this localized 'file-doesnt-exist' KavitaException. It is UI-facing and not Sentry-reported.

Source

Thrown at Kavita.Services/CacheService.cs:233

                    }
                    readingItemService.Extract(file.FilePath, Path.Join(extractPath, extraPath), MangaFormat.Image, files.Count);
                }
                directoryService.Flatten(extractDi.FullName);
            }

        }

        foreach (var file in files)
        {
            if (fileCount > 1)
            {
                extraPath = file.Id + string.Empty;
            }

            if (!directoryService.FileSystem.Path.Exists(file.FilePath))
            {
                logger.LogError("{File} does not exist on disk", file.FilePath);
                throw new KavitaException(await localizationService.TranslateAsync("file-doesnt-exist"));
            }

            switch (file.Format)
            {
                case MangaFormat.Archive:
                    readingItemService.Extract(file.FilePath, Path.Join(extractPath, extraPath), file.Format);
                    break;
                case MangaFormat.Epub:
                case MangaFormat.Pdf:
                {
                    if (extractPdfImages)
                    {
                        readingItemService.Extract(file.FilePath, Path.Join(extractPath, extraPath), file.Format);
                        break;
                    }
                    removeNonImages = false;

                    directoryService.ExistOrCreate(extractPath);

View on GitHub (pinned to 9c3e540000)

Solutions

Run a library scan or 'Scan Library' from the UI to sync the database with the actual disk state
Verify the file path exists on disk at the location stored in the database; if the library root moved, update the library folder path in Settings
Check file system permissions to ensure the Kavita process has read access to the library directory
If the file was intentionally deleted, remove it from the library via a scan so stale references are cleaned up

Example fix

// Before extracting, validate file existence and report a cleaner error:
// if (!directoryService.FileSystem.Path.Exists(file.FilePath)) {
//     logger.LogWarning("Skipping missing file {Path}", file.FilePath);
//     continue; // skip rather than abort entire extraction
// }

Defensive patterns

Strategy: try-catch

Validate before calling

// Check file existence before triggering cache extraction:
// var files = await unitOfWork.ChapterRepository.GetFilesForChaptersAsync(chapterIds, ct);
// var missing = files.Where(f => !File.Exists(f.FilePath)).ToList();
// if (missing.Any()) {
//     await libraryService.ScanLibrary(libraryId, ct); // sync DB with disk
//     return BadRequest("Some files are missing; running a library scan");
// }

Try / catch

// try {
//     await cacheService.EnsureCacheExtracted(chapterId, ct);
// } catch (KavitaException ex) when (ex.Message == "file-doesnt-exist") {
//     logger.LogWarning("File missing during cache extraction for chapter {ChapterId}", chapterId);
//     await mediaErrorService.ReportMediaIssueAsync(filePath, MediaErrorProducer.BookService, "File missing from disk", ex, ct);
//     return NotFound("The requested file no longer exists on disk");
// }

Prevention

Schedule periodic library scans to keep the database in sync with disk state
Avoid moving or renaming files in the library directory outside of Kavita
Use monitoring/alerting on MediaIssue reports to catch missing files early

When it happens

Trigger: A library file was deleted, moved, or renamed on disk after it was scanned into the database; a network share hosting the library was disconnected or remapped; file permissions changed making the file inaccessible; the database references a stale path from a previous server migration.

Common situations: User reorganizes their manga/comic folders without rescanning; a USB drive or NAS mount drops; files were moved by an external tool (Sonarr, Radarr, file dedup utilities); library root path changed after a server move.

Related errors

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