Skip to content

Repair the Image Registry

Stillwater keeps a registry of every artwork slot it knows about for each artist. If that registry loses rows, or marks artwork as missing when the file is still on disk, artwork appears to vanish from the interface even though nothing was deleted from your library.

The repair operation rebuilds that registry from the files already on disk. It never downloads artwork, never writes to your media server, and never deletes an image file -- it only corrects Stillwater's own records to match what it finds.

This is an exceptional recovery operation, not routine maintenance. Run it when artwork you can see on disk is missing from Stillwater, not on a schedule.

Run It From the Notice

When Stillwater thinks a repair is needed (see Background Check), the notice at the top of the page has a Repair now button. It is available to administrators only.

  1. Select Repair now and confirm. The confirmation lists, from the last background check, how many rows would be rebuilt and how many existence flags restored, and how long ago that check ran. It opens at once; nothing is scanned when you select the button. The numbers may have changed since (for example after files were added), and the toast in step 3 reports what the repair actually did. If the notice has no breakdown (a repair of the whole library just finished with changes it could not save), the confirmation is generic. It also says no image files are changed.
  2. The button reads Repairing... and is disabled while the repair runs in the background. A toast says the repair started.
  3. When it finishes, a toast reports the result:
    • Image registry repaired: N rebuilt, M restored. The repair completed. The notice checks the latest state and hides itself.
    • Image registry repair finished, but N changes could not be saved. Run it again. The repair is incomplete, so the notice stays. Run it again; it is safe to repeat.
    • Image registry repair failed. See the server log for details. The repair did not complete. The toast is deliberately generic; the full error is in the Stillwater server log.
  4. If a repair is already running (for example started from the API, or from another browser tab), a toast says An image registry repair is already running. and the button follows that run to its result instead of starting a second one.

The same repair is available through the API, shown below.

Preview First, Then Apply

The operation takes a commit flag and always runs in two steps.

Preview reports what would change and writes nothing at all:

curl -X POST https://<your-stillwater>/api/v1/reports/registry-repair/remediate \
  -H 'Content-Type: application/json' \
  -d '{"commit": false}'

Apply performs the same work and writes the corrections:

curl -X POST https://<your-stillwater>/api/v1/reports/registry-repair/remediate \
  -H 'Content-Type: application/json' \
  -d '{"commit": true}'

Both forms require authentication, and the request is subject to the same protections as every other state-changing call. Omitting commit previews.

The repair runs in the background because it can take several minutes on a large library. The request returns 202 Accepted at once; read the outcome from the status endpoint, repeating until running is false:

curl https://<your-stillwater>/api/v1/reports/registry-repair/status

The status reads idle, running, completed (the report below is under report) or failed (error says why). The status is kept in memory only. Restarting or shutting down Stillwater mid-run cancels the run, and afterwards the status reads idle, so a run that reads idle when you expected a result may have been cut off. Re-run it; the repair is safe to repeat.

The operation is safe to repeat. Running it twice in a row leaves the second run with nothing to do.

Repair a Single Artist

Pass artist_id to limit the work to one artist instead of the whole library:

curl -X POST https://<your-stillwater>/api/v1/reports/registry-repair/remediate \
  -H 'Content-Type: application/json' \
  -d '{"commit": false, "artist_id": "<artist-id>"}'

Reading the Report

The report field of a completed status summarizes the run, then repeats each pass's own detail underneath.

Field Meaning
scanned Artists whose image directory was read successfully
rebuilt Registry rows created for artwork found on disk
restored Existence flags corrected for artwork that is present
absent Artists whose directory is definitively not there
unreadable Artists whose directory exists but could not be read
skipped Artists with no resolvable image directory to examine
unverifiable_rows Rows that could not be checked, because their artist's directory could not be read
write_failures Corrections that were attempted but did not persist
dry_run Whether this was a preview
op_id Identifier for correlating the run with the logs

Three distinctions are worth understanding, because they are deliberately kept apart rather than merged into a single "problem" count:

  • absent is not unreadable. A directory that is genuinely gone is a different situation from one that exists but cannot be opened, and they call for different responses. The first usually means the artist's files really did move; the second usually means permissions.
  • skipped is neither. These artists have no location recorded to look at, so nothing was observed to be absent and no read was attempted. This is a gap in Stillwater's records, not a finding about your disk.
  • unreadable counts artists; unverifiable_rows counts rows. One unreadable directory holding several artwork rows is one unreadable artist and several unverifiable rows.

Every artist considered lands in exactly one of scanned, absent, unreadable, or skipped, so those four always account for the whole library.

A non-zero write_failures means the run did not fully complete, even though the request succeeded. Re-run the operation; it is safe to repeat.

Background Check

Stillwater runs a preview in the background every 12 hours (the first one two minutes after startup) and remembers whether anything needed repair, and how many rows it would rebuild and how many existence flags it would restore. The check never runs on demand, so the answer can be up to 12 hours old, except for the updates noted here and below. Completing a repair of the whole library updates it immediately.

Separately, Stillwater checks every hour (by default) that the artwork each existence flag points to is really on disk. It clears flags whose files are gone and, for backdrops only, sets flags back on when the files are there, so backdrop flags left cleared by an earlier problem heal on their own. When that restores any flags, it re-runs the preview so the notice reflects the new state, unless a repair or check is running at that moment (the next scheduled check then catches up). Missing rows, and flags for other image types such as thumbnails, logos and banners, are not healed this way and still need the repair above.

When the last check found rows that may need repair, administrators see a notice at the top of their pages with the number of rows and when they were last checked. It does not appear when the registry looks clean, when no check has finished yet, or for users who are not administrators. Close it with the X to hide it for the rest of your browser session; it returns in a new session while a repair is still needed.

What It Cannot Fix

Repair works from what is on disk, so it can only help artists it can locate. An artist with no recorded path is reported under skipped and is left alone -- there is nowhere to look. Artwork that was deleted from disk is genuinely gone and is not recreated; the operation corrects records, it does not restore files.

Responses

Status Meaning
202 The run started. Poll the status endpoint for the result
409 A repair is already running. Wait for it to finish

The status endpoint is always 200. A completed status with a non-zero report.write_failures means incomplete, not clean. A failed status with error_code library_unreachable means the library is not reachable, usually a mount that is down; nothing was changed.

A repair that is interrupted by Stillwater shutting down mid-run is simply cut off, and the status reads idle after the restart; re-run it. A run that exceeds the 30-minute work limit reads failed with error_code timeout.

Confirming the Result

Compare the report against the files themselves rather than against the counts alone. After a commit run completes, the artwork that was present on disk should now appear in Stillwater, and a second preview should report nothing left to do.