Recover an interrupted environment

The symptom

A command or a connect call fails with a recovery error:

$ ontoenv status
Error: OntoEnv recovery required: interrupted mutation marker at
./.ontoenv/catalog.pending; run `ontoenv recover` or call OntoEnv::recover
to rebuild the catalog

In Python this surfaces as ontoenv.CatalogRecoveryError.

This means a process stopped between changing the graph store and publishing the updated index. The store may contain changes that the index does not describe. OntoEnv refuses to use that index until recovery scans the stored graphs and replaces it.

The fix

$ ontoenv recover
Recovered catalog at ./.ontoenv with 12 ontology records.

from ontoenv import OntoEnv, CatalogRecoveryError

try:
    env = OntoEnv.connect("./ontology-env")
except CatalogRecoveryError:
    env = OntoEnv.recover("./ontology-env")

With a custom graph store, pass it:

env = OntoEnv.recover("./ontology-env", graph_store=store)

Recovery scans every stored graph and publishes a replacement index. It is much slower than a normal open, so it is not something OntoEnv does for you automatically.

ontoenv recover uses the same environment discovery as every other command: it walks up from the current directory and honours ONTOENV_DIR.

Warning

Do not delete .ontoenv/catalog.pending by hand. The marker is what tells OntoEnv the index is untrustworthy; removing it makes a possibly incomplete index look valid. recover removes it only after the replacement index is successfully published.

If recovery fails

Recovery requires a stable, fully readable snapshot of the backend. It aborts and leaves the marker in place if a graph cannot be read or the backend changes mid-scan — so the operation is always safe to retry.

Stop anything else writing to the environment, then run it again.

When this is not the problem

A missing owl:imports target does not leave a recovery marker. In non-strict mode, import_dependencies(..., fetch_missing=True) and get_dependencies(..., fetch_missing=True) are best-effort: they skip what they cannot reach and commit the partial result cleanly.

So a recovery marker always means an interrupted or failed commit, never merely an unresolved import. For missing imports, see Diagnose import problems.

Recovery is unavailable for temporary environments (--temporary / OntoEnv(temporary=True)), which have nothing persisted to recover from.

Start over instead

If you would rather rebuild from your source files than recover:

$ ontoenv reset
$ ontoenv init ./ontologies

These commands form a destructive sequence. reset asks for confirmation, then deletes .ontoenv/ entirely, including its catalog, stored graphs, and cached remote ontologies. init creates a new environment, scans ./ontologies, and follows its imports; remote imports must be downloaded again. The source files under ./ontologies are not deleted.