# 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
```

## 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
```

For manga with chapters:

```
Library Root/
├── Manga Title/
│   ├── Manga Title Ch 001.cbz
│   ├── Manga Title Ch 002.cbz
│   └── Manga Title Ch 003.cbz
```

For books/epubs:

```
Library Root/
├── Author Name/
│   └── Book Title/
│       └── Book Title.epub
```

**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:

```bash
curl -X POST "http://localhost:5000/api/library/scan?libraryId=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Method 3: Use ComicInfo.xml for Precise Metadata

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

```xml
<!-- 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>
```

ComicInfo.xml takes priority over folder-based naming. Tools like [ComicTagger](https://github.com/comictagger/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:

```bash
# 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
```

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

## Prevention

- Establish a naming convention before adding files — follow Kavita's [wiki on naming](https://wiki.kavitareader.com/en/guides/scanner/manganaming)
- 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

- [How to Self-Host Kavita](/apps/kavita)
- [Best Self-Hosted Ebook Managers](/best/ebooks-reading)
- [Kavita vs Calibre-Web](/compare/kavita-vs-calibre-web)
- [Komga vs Kavita](/compare/komga-vs-kavita)