File Paths, Backups, and Recovery¶

Goal¶

Recover from missing originals, unavailable destinations, preview-cache issues, pending recovery mirrors, or catalog-open problems, and create a verified catalog backup without confusing it with an original-media backup.

Last reviewed: 2026-08-31 against the current catalog schema-v9 recovery, restore, scheduled-backup, stable-folder, cache, and atomic-publication contracts.

Applies to¶

Ravo Studio's local catalog and preview cache.
Local ravo CLI workflows.
Catalog-owned recovery mirrors and CLI/Studio backup, restore, scheduling, preview rebuild, and stable-folder relink.

Original files are references¶

Import records a normalized local path and a source fingerprint. It does not copy the source into the library. Normal editing, preview generation, metadata changes, and rendered export do not rewrite it.

This makes the source folder part of the library's operational setup. Keep the source readable at the recorded path, or keep a filesystem layout that resolves the same path when moving a catalog between machines.

Missing original¶

Typical signs are:

A thumbnail or image surface says Missing.
The right Photo panel still shows catalog review state but no new preview can be generated.
Export returns an original-not-found error.

The catalog record, rating, color label, reject state, tags, metadata, recipe, and history remain stored. Restore the file to its recorded path, then select the asset again so Studio can request a new preview.

When an entire directly cataloged folder moves, Studio marks that stable folder as missing; click its missing row and choose the replacement directory. Ravo requires the old directory to be unavailable and validates every expected basename, size, modification time, and stored fingerprint before one catalog transaction changes paths. The CLI equivalent is:

ravo catalog folders --catalog "/work/Ravo Library.sqlite" --json
ravo catalog folder-relink --catalog "/work/Ravo Library.sqlite" \
  --folder-id <folder-id> --replacement "/new/photo/folder" --json

This is not a fuzzy filename search. An individually renamed file, a changed copy, or a hierarchy-only parent without a stable ID is not guessed. Do not delete a catalog record merely because its source is temporarily unmounted.

Preview cache¶

The default cache is adjacent to the catalog:

<catalog>.preview/

It contains rebuildable PNG previews and is not the source of truth for recipes or review state. If a cache entry is missing, Ravo can regenerate it from a readable original. If the source is missing, cache regeneration cannot succeed.

Do not treat a cached preview as an archival copy of the original RAW or raster file. Verified catalog backup deliberately excludes this cache.

Catalog-owned recovery mirrors¶

Durable catalog state has a separate support root:

<catalog>.ravo/sidecars/

Each asset's current generation is a bounded, checksummed .ravo.json snapshot of source identity, review/capture state, tags, writable metadata, recipe, and history. These files are derived from SQLite after a successful catalog commit. They are not placed beside originals, are never imported automatically, and do not become a second live edit authority.

Studio and the CLI retry pending generations when a catalog opens or closes. Inspect or explicitly synchronize them with:

ravo catalog sidecar-status --catalog "/work/Ravo Library.sqlite" --json
ravo catalog sidecar-status --catalog "/work/Ravo Library.sqlite" \
  --asset-id <asset-id> --json
ravo catalog sidecar-sync --catalog "/work/Ravo Library.sqlite" --json

Without --asset-id, status lists pending generations only. A mutation can commit to SQLite while filesystem publication fails; the error then reports catalog_committed=true and recovery_pending=true. Do not repeat the catalog edit blindly. Repair the support-directory problem and run sidecar-sync or reopen the catalog.

Do not hand-edit, rename, or copy one recovery JSON back into the live catalog. Use a complete verified backup for catalog restore.

Create and verify a catalog backup¶

For a healthy catalog, prefer the supported backup command over copying a live SQLite filename:

ravo catalog backup --catalog "/work/Ravo Library.sqlite" \
  --backup "/backups/Ravo-2026-08-31" --json
ravo catalog backup-verify --backup "/backups/Ravo-2026-08-31" --json

The backup destination must not exist. Creation drains pending recovery, integrity-checks and snapshots the live database, removes rebuildable preview rows, copies the exact recovery generations, verifies the staged result, and publishes the directory without replacement. The result has exactly:

Ravo-2026-08-31/
├── catalog.sqlite
├── manifest.json
└── sidecars/

backup-verify is self-contained and takes no --catalog; it verifies the strict layout, hashes, identities, sidecar generations, SQLite integrity, and the absence of preview rows without opening the snapshot as a live library.

Restore to an explicitly absent catalog path, then rebuild previews as needed:

ravo catalog backup-restore --backup "/backups/Ravo-2026-08-31" \
  --output "/work/Restored Ravo Library.sqlite" --json
ravo catalog preview-rebuild --catalog "/work/Restored Ravo Library.sqlite" --json

Restore verifies the complete source and staged copy, publishes the support directory first and catalog file last, then reopens the result through the ordinary catalog path. It never overwrites or merges a destination. Studio exposes create, verify, restore, recovery sync, and selected/all preview rebuild under File → Recovery with progress and cancellation.

To configure recurring verified backups from the CLI:

ravo catalog backup-policy --catalog "/work/Ravo Library.sqlite" \
  --schedule-dir "/backups/Ravo" --interval-minutes 1440 \
  --retention-count 7 --enabled true --json
ravo catalog backup-run --catalog "/work/Ravo Library.sqlite" --json

Studio exposes the same schedule. Retention deletes only canonical scheduled artifacts that reverify as the current catalog; unknown, changed, symlink, or user-created paths are retained.

Warning

A verified catalog backup excludes originals and previews. Back up every referenced original separately. Restore and scheduled retention still do not contain or back up originals, and there is no cloud destination.

Catalog open errors¶

Catalog database does not exist: use Open Library on the correct path, or create a new library.
Catalog database already exists: Create Library will not overwrite it; choose another path or open the existing file.
Catalog is missing schema information / invalid: the file is not a valid Ravo catalog or is damaged. Preserve a copy before attempting recovery.
Catalog schema is newer than this Ravo: use a Ravo build that understands that schema; the current build does not downgrade it.

Ravo's catalog schema is independent from the old application. Do not point Ravo at a legacy database and expect an in-place migration.

Output path problems¶

Rendered export and original-copy export use atomic no-replace publication:

An existing destination returns conflict.
A missing or unwritable parent directory returns an I/O failure.
A cancelled or failed write does not become a successful partial export.

Choose a new output path and verify that its parent directory is writable. If a previous output is important, preserve it before retrying.

Safe recovery sequence¶

Stop the current import or export if it is still running.
If the catalog still opens, inspect pending recovery and create then verify a new backup at an absent destination.
Verify that every required original path exists and is readable; remember that the catalog backup does not contain those files.
If the live catalog cannot be trusted, restore the verified backup to a new absent catalog path and open that restored catalog.
Rebuild the affected previews, then verify the image, review state, recipe, and history.
Export to a new destination and check the result independently.

If the catalog cannot open, close every Ravo process before making a forensic filesystem copy. Preserve the catalog, its .ravo support directory, and any same-name SQLite -wal / -shm files that still exist. That raw copy is not a verified Ravo backup, but it avoids destroying evidence before diagnosis.

Result¶

Recovery distinguishes catalog records, recovery mirrors, verified backup artifacts, source files, cache files, and outputs. Work on the affected layer without deleting another one or mistaking verification for restore.

Common questions¶

Can I delete the `.preview` directory to fix a stale preview?¶

Previews are rebuildable, but remove or replace cache data only when Studio is closed. First create and verify a catalog backup when the library is healthy, and preserve the originals separately.

Will reopening the catalog relink moved photos?¶

Reopening detects a missing stable direct folder but does not guess its new location. Use the missing-folder row in Studio or catalog folder-relink with the explicit folder ID and replacement directory.

Does Remove from Catalog delete the original?¶

No. Remove from Catalog leaves the original on disk. Delete from Disk is the separate, confirmed, irreversible action.

Can I open `catalog.sqlite` inside a backup directly?¶

No. backup-verify treats the directory as a read-only artifact. Use backup-restore to publish the complete verified artifact to a new absent live catalog path.