DEV Community

selfhosting.sh
selfhosting.sh

Posted on • Originally published at selfhosting.sh

Kavita Metadata Issues

The Problem

Kavita shows the wrong metadata for your books, covers aren't appearing, series aren't grouped correctly, or the library scan completes but books show generic placeholder information. Common symptoms:

- Books show as "Unknown" series or author
- Cover images are missing or show the wrong cover
- Multiple series that should be one are split into separate entries
- Scan completes but new files aren't detected
- Metadata from Kavita+ or ComicVine doesn't match
Enter fullscreen mode Exit fullscreen mode

The Cause

Kavita relies heavily on file and folder naming conventions to identify series, volumes, and chapters. Unlike Calibre-Web, which uses a database file, Kavita infers metadata from your directory structure. The most common causes:

  1. Incorrect naming convention — Kavita expects a specific folder/file naming pattern
  2. Mixed naming formats — inconsistent file naming within a series
  3. Scanner cache — Kavita caches scan results and won't detect changes until a full rescan
  4. ComicInfo.xml / OPF conflicts — embedded metadata in files conflicting with folder-based detection
  5. Kavita+ API key issues — metadata enrichment failing silently

The Fix

Method 1: Fix Your Directory Structure (Most Common)

Kavita expects this directory layout:

Library Root/
├── Series Name/
│   ├── Series Name Vol 1.cbz
│   ├── Series Name Vol 2.cbz
│   └── Series Name Vol 3.cbz
Enter fullscreen mode Exit fullscreen mode

For manga with chapters:

Library Root/
├── Manga Title/
│   ├── Manga Title Ch 001.cbz
│   ├── Manga Title Ch 002.cbz
│   └── Manga Title Ch 003.cbz
Enter fullscreen mode Exit fullscreen mode

For books/epubs:

Library Root/
├── Author Name/
│   └── Book Title/
│       └── Book Title.epub
Enter fullscreen mode Exit fullscreen mode

Common mistakes:

Wrong Right
comics/batman (2016)/batman_001.cbz comics/Batman (2016)/Batman (2016) Vol 1.cbz
manga/one piece/ch1.cbz manga/One Piece/One Piece Ch 001.cbz
books/book.epub (no folder) books/Author/Title/Title.epub

The series name in the folder must match the series name in the filename. Kavita uses this to group files into a single series.

Method 2: Force a Full Library Scan

Kavita's scanner caches results. After renaming files, a quick scan may not pick up changes:

  1. Go to Dashboard → Library (click the library name)
  2. Click the three-dot menu → Scan Library
  3. If that doesn't work, click Analyze Files (reprocesses all metadata)
  4. For stubborn issues, click Refresh Covers to regenerate all cover images

You can also trigger a scan via the API:

curl -X POST "http://localhost:5000/api/library/scan?libraryId=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Enter fullscreen mode Exit fullscreen mode

Method 3: Use ComicInfo.xml for Precise Metadata

For comics and manga, embed metadata directly in the archive file:

<!-- ComicInfo.xml (place inside the .cbz/.cbr archive) -->
<ComicInfo>
  <Series>Batman</Series>
  <Volume>2016</Volume>
  <Number>1</Number>
  <Title>I Am Gotham, Part One</Title>
  <Writer>Tom King</Writer>
  <Publisher>DC Comics</Publisher>
  <Year>2016</Year>
  <Month>8</Month>
</ComicInfo>
Enter fullscreen mode Exit fullscreen mode

ComicInfo.xml takes priority over folder-based naming. Tools like ComicTagger can batch-add this metadata.

For epubs, Kavita reads OPF metadata embedded in the epub file. Use Calibre to edit epub metadata if it's wrong.

Method 4: Fix Kavita+ Metadata Enrichment

If you're using Kavita+ for enhanced metadata but it's not working:

  1. Go to Settings → Users → Your Account → Kavita+
  2. Verify your API key is entered correctly
  3. Check that your instance can reach api.kavitareader.com (no firewall blocking)
  4. After adding the key, go to a series → click three-dot menu → Refresh Metadata

Kavita+ matches using series name, so if your naming is wrong (Method 1), the lookup will also fail.

Method 5: Clear Kavita's Cache

If metadata is stuck showing old/wrong data after fixes:

# Stop Kavita
docker compose stop kavita

# Delete the cache directory (inside the config volume)
# Find where your config volume is mounted
docker volume inspect kavita-config

# Remove cache files (covers and temp data)
sudo rm -rf /path/to/kavita-config/cache/*
sudo rm -rf /path/to/kavita-config/temp/*

# Restart and trigger full scan
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Then go to Dashboard → Library → Scan Library → Analyze Files.

Prevention

  • Establish a naming convention before adding files — follow Kavita's wiki on naming
  • Use ComicInfo.xml for comics/manga to avoid reliance on folder naming
  • After bulk-renaming files, always run a full library scan (not a quick scan)
  • Keep library folders clean — avoid mixing different series in one folder
  • Use zero-padded chapter numbers (Ch 001, not Ch 1) for correct sort order

Related

Top comments (0)