<!-- Ground truth: templates/admin_processing_issues.templ (stats cards,
     Retry all queue, per-issue Retry/Dismiss, severity badges),
     internal/handlers/processing_issues.go (RetryProcessingIssue — success
     closes the issue, failure returns the real error; resolve path),
     internal/router/library.go (issue routes), the deliberately-not-a-
     library-rescan design comment in the template. Re-verify against these
     when the page changes. -->

# Processing Issues

Processing Issues is each library's ledger of items the scanner could not
fully process — a corrupt file, an unsupported format, metadata that
wouldn't parse. It is per-library: you reach it from that library's panel
on the [Libraries](libraries.md) page (the link only appears when the
library has issues).

## What's on the page

Three count cards — **Errors**, **Warnings**, **Info** — show how many
open issues sit at each severity (a card only appears when that severity
has issues). Below them, one card per issue showing:

- the item's **title** and a plain-language **description** of what went
  wrong
- **Type**, **Format**, **File** (full path), and **Library** type
- a severity badge: red for errors, amber for warnings, neutral for info

## Fixing an issue

### Retry

Runs that one item back through the scanner. This is a per-item scan —
the item's file is re-read and re-extracted exactly like a book-page
[Rescan](scanning.md), not a pass over the library. If it succeeds, the
issue closes itself; if it fails again, the page shows the *real* error,
so you know why it still fails instead of staring at a stale complaint.

### Retry all

Queues every issue currently on the page and works through them **one at
a time** — the button shows progress as "done / total" while the queue
drains. This is deliberately not a whole-library scan: fixing a handful of
bad files never re-reads the good ones. Per-issue **Retry** buttons are
disabled while the queue is running.

When the queue finishes, the page refreshes itself from the server —
closed issues disappear, still-failing ones stay with fresh error text.

### Dismiss

Closes an issue without re-processing — for warnings and info items you've
looked at and judged fine (a confirm dialog guards the click). **Errors
cannot be dismissed**: they must be fixed and successfully retried. The
Dismiss button simply doesn't exist on an error card.

## How issues get here and leave

The scanner creates an issue whenever it fails to process an item during a
scan. Issues leave the page three ways: a successful **Retry** (or any
later scan that processes the item cleanly), a **Dismiss** you chose for a
warning or info item, or the file's problem being fixed on disk and the
next scan handling the item cleanly.