Troubleshooting and FAQ

Library

Some thumbnails stay grey or marked “Missing”

Catalog cannot find the file at the recorded location: the disk is unplugged, or the folder was moved or renamed in the Finder. Plug the disk back in. If the folder has moved (or the library is opened on another Mac), right-click the folder in Imported folders, then Locate folder…: its files are relinked to their new location after their fingerprint is checked, and keep their metadata, tags, collections, versions and links to works (see Locating a moved folder). Importing it again at its new place also finds its files by their fingerprint, but makes it another imported folder and leaves the former one empty. A file renamed or put in a subfolder of an imported folder is found again by Import again (see Renamed or moved files).

“The library could not be opened”

This is the title of the screen shown when Catalog cannot open the library; the sentence below says why (the following cases). Try again retries. Without another explanation, check that the library folder (by default ~/Library/Application Support/Obscura Catalog/) exists and that the disk is not full.

“… cannot be found”

The library chosen in Catalog (moved to an external disk, or opened from another folder) is not there: the disk is unplugged, or the folder was renamed or moved in the Finder. Catalog does not create an empty one in its place. Plug the disk in, then Try again. If the folder has moved, File › Open Library… opens it where it is (see Moving the library). A chosen folder that is not a library is refused: “… is not an Obscura Catalog library (no readable Catalog.sqlite).”

“This library’s database is damaged”

When opening, SQLite found a fault in Catalog.sqlite (a failing disk, an interrupted copy); the message gives SQLite’s code in brackets. Catalog does not open it and writes nothing to it. Open Obscura Catalog › Settings… › Backup and restore the most recent backup (see Backing up and restoring the library): the damaged files are kept as they were under Before restore.

“The library … is already open in another copy of Obscura Catalog”

Another copy of the app (another installed version, a copy run from source) has the library open. Quit it, then Try again. A library opens in one copy at a time: two copies writing to the same database would damage it.

“This library was saved by a newer version of Obscura Catalog”

The library was updated by a newer version of the app (for instance after an older version was reinstalled); the message names the migrations this version does not know. To keep it safe, this version does not open it and writes nothing to it: the library is intact. Install the latest version of Obscura Catalog, then open it again. A backup written by a newer version is likewise refused on restore.

To go back to an older version on purpose, see the next question.

“This folder is on a network volume” or “This folder is synced…”

Catalog refuses to create or move a library on a NAS, a network share (SMB, AFP, NFS, WebDAV) or in a synced folder (iCloud Drive, Google Drive, Dropbox, OneDrive, Box): a dropped connection, or a sync that copies its files separately, would damage the database, and two Macs could open it together. Choose a folder on this Mac’s disk, or an external disk plugged in directly. If your library is already there, Catalog opens it but says so at launch (“The library is not on a local disk”): Move the library… opens Settings › General, where Move… puts it on a local disk. Backups and exports may go to a NAS or a synced folder.

I work on two Macs

Do not share a library over the network or through a synced folder. Two safe ways (see Moving the library, keeping several libraries):

the library on an external SSD, plugged into one Mac at a time: quit Catalog before unplugging the disk, then open it on the other Mac (File › Open Library… the first time);
one library per Mac: hand the work over through a backup copied to the other Mac’s disk and opened there, or through a full export.

“The copy could not be opened at this location”

Moving to another disk copied and checked the library, but the copy could not be opened at its destination (a disk that refuses SQLite’s journal, a network share for instance). The copy was removed, and the library stayed where it was, intact: Catalog relaunches on it. Choose another disk.

“A task is running: …”

Restoring a backup, opening, creating or moving a library, or relaunching for a new language waits for an import, an export or a package for Vault to end: the message names the task. Wait for it to finish, or stop it on its screen (Stop), then try again. Quitting during such a task asks first: Cancel or Stop and quit.

Going back to the previous version of Obscura Catalog

An update can change the library’s database (a migration): an older version then refuses to open it (see the previous question), and Obscura Catalog never offers to go down a version. If a new version blocks you, you can go back to the previous one with the database as it was just before the update. What you entered since will not be in it: use this only as a last resort, and report the problem to us (see Where can I get help?).

Two copies of the database can serve:

a pre-migration copy, in the library folder: Catalog writes it, and checks it, just before applying a migration, and does not migrate if it could not write it. It carries the number of the schema it holds, the one before the update: Catalog.pre-migration-v20.sqlite, for instance. Catalog keeps the last two: you can go back up to two schema versions. An update that does not migrate writes none; an update that applies several migrations at once writes only one;
a backup in Backups/ (see Backing up and restoring the library): its backup.json file names the version of Catalog that wrote it (appVersion). Choose a backup written by the version you are going back to, or by an older one.

Which pre-migration copy to choose:

the one with the highest number is the database just before the last migrating update: it is the one you need to go back to the previous version;
the other is the database just before the migrating update before that: it takes you one schema version further back, and does not hold what you entered in between.

The copies are not backups: they do not appear in Settings › Backup, are not part of their rotation, and neither a backup, nor a full export, nor a package for Vault carries them. Older versions of Catalog wrote only one, Catalog.pre-migration.sqlite, replaced at each migration: at its first opening, the new version renames it after its schema’s number. If it keeps that name, Catalog could not read its schema: do not use it.

Then:

Quit Obscura Catalog (Obscura Catalog › Quit).
In the Finder, Go › Go to Folder…, ~/Library/Application Support/Obscura Catalog/ (or your library’s folder if you moved it). Copy the whole folder somewhere else, preferably to another disk: it is your safety net if something goes wrong.
In that folder, create a folder named “Library of the newer version” and move Catalog.sqlite into it, with Catalog.sqlite-wal and Catalog.sqlite-shm if they exist. Nothing is lost: the newer version opens it again with File › Open Library….
Copy the chosen file (the pre-migration copy, Catalog.pre-migration-v20.sqlite for instance, or the backup’s Catalog.sqlite) into the library folder, and rename the duplicate Catalog.sqlite. Keep the original as it is.
Download the disk image of the previous version. Every published version stays available, never replaced, on request: write to us from the Contact page, stating the version you need. Open it and drag Obscura Catalog onto the Applications folder, replacing the installed app.
Open Obscura Catalog: it opens the library without a migration. Check your works. When it offers the newer version, choose to skip that version, or turn off Automatically check for updates in Settings › Updates, until the problem is fixed.

If Catalog answers “This library was saved by a newer version”, the copy you chose comes from a newer version than the one installed: take the pre-migration copy with the lower number or an older backup, or install the version that wrote it.

What the restored database does not know: documents attached since the update (their copies stay in Documents/, unlinked) and certificates issued since (their PDFs stay in Certificats/, but they are no longer in the register); write them down before you carry on. When a fixed version is released, it migrates the database again, with what you entered in the meantime.

How large a library does Catalog handle, and how much space should I plan?

Catalog is tested with a library of 250,000 files spread over three disks, one of them unplugged, on a 2019 Intel Mac: the grid opens and scrolls without waiting, ⌘A selects everything at once, filters, sorts and smart collections answer in under a second, a search across all fields in about a second, and the analysis does not re-read the files of an unplugged disk batch after batch. Beyond that size, nothing is measured.

At that size, a few operations take time: opening the library (about 30 seconds at the first launch after the Mac restarts), a backup (about 25 seconds, during which changes wait), the full export (3 to 4 minutes) and the search for duplicates in Similar photos (half an hour; the photos similar to a given photo show in a fraction of a second).

The space to plan on the library’s disk, per 10,000 photos:

	Per 10,000 photos
The database (`Catalog.sqlite`), photos analysed	about 100 MB
The thumbnails (`Derivatives/`)	about 600 MB
The previews (`Derivatives/`): each photo opened large, and each work’s reference image	about 1 MB per photo concerned
The backups (`Backups/`)	the size of the database, for each backup kept (10 by default)

For 150,000 photos, plan about 1.5 GB for the database, 9 GB for the thumbnails and 15 GB for ten backups, about 25 GB in all, plus the previews. Settings › Backup › Keep n backups reduces the last line. The photos themselves stay where they are: Catalog does not copy them.

Import folder by folder (a disk, a year, an assignment) rather than the root of a whole disk: each folder becomes its own imported folder, a stopped import resumes where it stopped, and you work on one folder while the next one imports. On the catalogue’s side, a folder of 50,000 photos takes 4 to 9 minutes depending on the library’s size, plus reading each file whole on its disk (for its digest), which depends on the disk. During a large import, follow it from Imports rather than from the Library grid: with 250,000 files, the import runs twice as fast when the grid is not shown.

My import stopped halfway

What was recorded stays. Open Imports › Fichiers (Files): the import is listed under Interrupted imports, and Resume continues it (see Stopping and resuming an import). The same goes for a Lightroom import, under Imports › Lightroom.

Some files were not imported

Expand “n failures” in the end-of-import banner: each file has its reason. “Unreadable file: its digest could not be computed” usually points to a damaged file, a disk dropping out or insufficient access rights.

I imported the same folder twice

Catalog recognises a folder by its path: importing the same folder only performs an incremental update. A folder copied elsewhere is another imported folder; its files are duplicates, skipped by default.

The keywords I changed in Lightroom do not show up

Catalog reads XMP sidecars on import and on Read the file again. A Lightroom catalog is taken over through the Lightroom import; run again, it only adds the photos that are missing.

CSV import

“This file is … MB: an inventory over 64 MB is not read”

The chosen file is probably not the inventory (a disk image, a video, an archive). A 50,000-row inventory weighs a few megabytes. For exhibitions and publications, the message is “This file cannot be read, or it is larger than 50 MB.” Check the file, or export the sheet as CSV again.

I cannot go on to the preview

“Assign a column to the catalogue number to continue”: one column must carry the Catalogue no. (see Columns). For exhibitions, the exhibition title is needed; for publications, the title or the full reference.

Some rows are rejected

The preview gives the reason for each rejection, and Save rejection report… saves it so you can fix the spreadsheet (see Preview). The most frequent: an ambiguous date (12/03/1974: write 1974-03-12), a number already in the catalogue (a number is never reissued, even a deleted work’s), an unknown agent not yet decided in Unknown agents.

“Import cancelled — nothing was written.”

A CSV import is written in a single transaction: stopped (Stop) or interrupted, it has written nothing at all, and the preview stays on screen. Run Import again. There is nothing to resume or undo, unlike a folder import.

The import is refused beyond 50 works

Without a licence, the catalogue holds at most 50 works: the import checks before writing that all the accepted rows fit, and otherwise refuses everything, with the reason. See Licence.

Metadata

“The file cannot be found: nothing was saved”

The sidecar and writing into the file need the file on disk. Plug the disk back in, or save to The catalogue only.

The “file itself” option does not appear

It is only offered for JPEG, TIFF, PNG and HEIC/HEIF. A RAW file cannot take metadata without being re-encoded: Catalog writes an XMP sidecar.

“is too long for IPTC”

The field exceeds the IPTC limit (64 characters for a title or a keyword, 128 for rights, 256 for the creator, 2,000 for the description): Bridge and Lightroom would truncate it. Shorten it.

Catalogue raisonné

“Publish” is refused

The message says why:

“Publishing requires an accepted attribution.” — add an attribution in the photographer role and accept it; “Anonymous” is one;
“This work is x% complete; publishing requires at least y%.” — follow the Next link (⌘⇧M) to fill in the missing criteria, or lower the threshold in Settings › Catalogue (see Completeness).

I cannot change the numbering

The numbering settings (Settings › Catalogue) are locked as soon as a work has received a number, even if it has since been deleted: a corpus has only one citation format.

I deleted a work and its number is not reused

That is intentional: a number is never reissued, because it may already have been cited or written on an object.

The search does not find a work

Check how the word is spelt rather than its accents (they are ignored), and that a number is typed whole (1975, or 19* for a beginning). Amounts and prices are never searched. If the work still cannot be found, use Rebuild search index in the ⋯ menu of the works list (see Searching).

I cannot delete a work

The message says why:

“A published work cannot be deleted: withdraw it; it stays citable.” — Withdraw unpublishes it while keeping its number;
“A withdrawn work cannot be deleted: it stays citable and resolvable.”;
“Certificates (…) refer to this work or its prints: it can’t be deleted.” — revoke them, or withdraw the work.

I cannot delete an agent

“This agent is still referenced: … It was not deleted.” The message names what references it, with a count: attributions, prints, provenance events, auction sales, conservation interventions, rights in works, exhibitions, publications, certificates, series defaults, series defaults’ rights; and the works concerned. Remove those references first; if the agent duplicates another entry, merge it instead from Possible duplicates, which moves its references (see Duplicates and merging).

“The copy of this document cannot be found in the library”

Catalog keeps a copy of every attached document, in the library’s Documents folder; that copy is what opens, not the original. If it is missing (library folder copied by hand without that folder, file deleted), restore the library folder from a backup, or attach the document again. An export describes such a document without its file, and says so.

A print shows “Numbers to correct”

The edition size changed after the prints were created; their frozen number no longer matches. Renumber updates them. A print a certificate cites (issued by Catalog, even superseded or revoked, or noted in its Certificate no.) keeps its number: Catalog names it with its certificate and renumbers the others (see A print’s number).

Exports

My LIDO export is missing some works

Confidential works are always excluded from it. Check the Confidential record box in their record.

An event, a sale, an intervention or a document is missing from the export

It is confidential: a provenance event is by default (and always while a party is a living person), its auction sale follows it, a conservation intervention can be, a document is when its box is ticked (by default for an invoice) or when it proves a confidential event. LIDO and CIDOC never carry it; the CSV, the full export and the package only with Include confidential records and a justification (see The confidentiality rule). Amounts never go into LIDO or CIDOC, and an intervention’s cost only into a CSV that includes the confidential records.

“Not enough space on this disk: the export needs …, … are free”

Before writing, the full export and the package for Vault compare the space they need (images or originals to copy included) with the free space of the chosen disk. Nothing was written. Free some space, choose another disk, or untick Copy the images (or Copy the originals into the package).

“The check against the manifest failed”

Catalog reads back every file written before giving the export or the package its name; a file that does not match (a failing disk, a file changed while being written) makes it abandon everything: nothing is kept. Start again, on another disk if the failure repeats.

“… cannot go into a package (name too long, hidden or with a control character)”

A file or folder name in the library is not accepted by the exchange contract with Obscura Vault. Rename it in the Finder (then Locate folder… if it is an imported folder), and start again. Nothing was kept.

Certificates and reports

“Issue…” is greyed out

Issuing is blocked while a signing key, its backup, an issuer or the public key publication URL is missing. The section’s banner says which; Open certificate settings opens Settings › Certificates (see Before the first issue).

A work cannot be certified

It must be validated or published, have an accepted attribution in the photographer role, and not be confidential. If it already has a valid certificate, re-issue it.

“The keychain could not be read”

The macOS keychain, where the signing key is kept, is locked, or Obscura Catalog was denied access to it. This is not “no key”: Catalog does not create a key over it or restore anything while it cannot read it, and issuing is blocked. Unlock the keychain or allow access, then Try again in Settings › Certificates (see Certificate settings).

“The timestamp authority delivered no token”

Nothing was issued. Try again, or clear the authority’s address in Settings › Certificates to issue without a timestamp.

I changed Macs

In Settings › Certificates, Restore… the key from its backup, with its passphrase. Without a backup, the key cannot be recovered.

A certificate has a mistake

Re-issue it: it keeps its number, and the previous version becomes “Superseded”. A clerical error does not justify a revocation.

A verification says “Intact signature, unknown key”

The certificate was signed by a key this installation does not know (issued from another library). Its signature has not been altered, but Catalog cannot tell who issued it.

My report is missing some works

A report never includes confidential works, and only the statuses chosen under Works (by default, validated and published).

Licence

“This feature requires an Obscura Catalog licence”

The LIDO or CIDOC export, issuing more than 10 certificates, creating a second library or removing “Made with Obscura Catalog” from the colophon requires a licence; the insurance inventory and the other management reports meant for third parties require the Pro or Studio plan. The Lightroom import does not. Sign in through Obscura Catalog › Activate Obscura Catalog… with the account that holds your licence (see Licence and free tier).

“The free tier allows 50 works; you already have …”

Without a licence, the catalogue holds at most 50 works (creating a work, creating works from files or a CSV import that would go beyond the limit is refused). You can still browse, edit and export as CSV those that exist; a licence lifts the limit.

“The free tier allows 1 library; you already have 1.”

Without a licence, you create one library on this Mac (the standard library counts). Your other libraries still open, to browse, search and export them (File › Open Library…). A deleted library frees its place. Creator creates one library, Pro five, Studio any number.

“The free tier allows 10 certificates; you already have …”

Free certificates are counted on this Mac, across all libraries: a new library does not reset the count. Verifying, reading the register and revoking stay free; a paid plan issues without limit.

“This account has no Obscura Catalog licence”

An Obscura Flow or Obscura Vault licence does not cover Catalog: each app has its own. Also check that you are signed in with the right account (Switch account in the activation window).

“Licence needs checking”

Catalog has not been able to confirm the licence for too long (30 days offline, unless the server set a longer period), or the Mac’s clock has been set back. Check the Mac’s date and time, connect the Mac to the Internet, then Check now in Account & Licence. Meanwhile, everything that needs no licence keeps working.

“The licence is dated in the future: check this Mac’s date and time”

The Mac’s clock is behind the licence’s date. Set the Mac’s date and time (preferably automatically), then Check now in Account & Licence.

“This licence was issued for another Mac”

The licence server issues each licence for a given Mac, and the one Catalog found was issued for another (a licence folder copied from another Mac, for instance). The paid features stay closed until this Mac has its own; everything else keeps working. Connect this Mac to the Internet: Catalog asks for the licence again by itself, or click Check now in Account & Licence. The server then issues a licence for this Mac, which takes a device seat (see “Device limit reached”).

“Device limit reached”

The licence is already in use on the maximum number of devices of your plan, and this Mac is one too many: the paid features are closed, the session stays open (it is not an expired session, there is no need to sign in again). Click Manage devices… in the message of the refused feature, or open Account & Licence, Devices section. The server grants the licence to the most recently seen devices: Revoke this device… on a Mac you no longer use (not the one marked This Mac), then confirm. Catalog checks the licence again at once; otherwise, Check now. See Device limit reached.

“Automatic Updates Off in This Copy”

This copy of Obscura Catalog is not the published, signed and notarized release (for example a copy built from source or signed locally): it does not look for updates. Install the disk image from the download page (see Download and install).