Guide: Instance Recovery (v5.0+)
How to recover a CryoSPARC instance if the database directory is corrupted or lost.
The CryoSPARC Database
CryoSPARC uses a database engine (MongoDB) under the hood to store information about the CryoSPARC instance, projects, jobs, users, etc. MongoDB stores this data on the filesystem, in a database directory that is created when CryoSPARC is installed. The contents of the database are necessary for CryoSPARC to function.
The above diagram shows how data is managed in CryoSPARC during normal operation.
If for some reason, the CryoSPARC database files become lost or corrupt, information from the project directories and instance configuration export can be used to recover the contents of the database, if the following are true:
project directories are intact, and
a recent instance configuration export file is available (these are produced automatically every 60 minutes by default in CryoSPARC v5.0+ and stored in the
cryosparc_master/rundirectory).
This guide describes new utilities in CryoSPARC v5.0+ that make it easy to recover a CryoSPARC instance in this scenario.
If for some reason, project directories are intact but a recent instance configuration export file is not available, it can still be possible to recover the instance manually by installing a new CryoSPARC instance, creating users, and then re-attaching all projects that were previously attached to the lost instance.
The next section provides the detailed steps to recover from a loss or corruption of the CryoSPARC database directory. The final section of this page gives the steps that can be used to migrate a CryoSPARC instance to new infrastructure, in a scenario where the database directory cannot be preserved.
Recovery from a lost or corrupt database
During instance recovery, information from the project directories and the instance configuration export file are combined to recreate the contents of the CryoSPARC database.
Prerequisites
Intact project directories mounted on the CryoSPARC master computer at the same path(s) as before the database loss
A recent instance configuration export file from the original instance (e.g.
cryosparc_instance_config_2025_09_29_13h49.tar)Instance configuration files are exported once per hour to
cryosparc_master/run/while CryoSPARC is runningIt is best to use the latest export available to minimize discrepancy between the exported configuration files and the previous database data before it was lost.
Reliable storage with enough space for the recovered database, allowing for future growth, mounted on the CryoSPARC master computer.
cryosparc_master/installation with the same version as the original instance at the time of database losscryosparc_worker/installation(s) with the same version as thecryosparc_master/installation
Steps
This process may take a significant amount of time for instances with many/large projects.
If CryoSPARC is running, stop CryoSPARC with
cryosparcm stop.Confirm, using Linux process query and management commands, that CryoSPARC has been stopped completely.
Locate the latest available configuration export file from the original instance. In CryoSPARC v5.0+, an updated version of this file is produced every 60 minutes while an instance is running, and is stored in the
cryosparc_master/rundirectory. The filename will be similar tocryosparc_instance_config_2025_09_29_13h49.tar.Make a copy of the latest available configuration export file, placing the copy in a location outside the original CryoSPARC installation, for example:
/home/cryosparcuser/latest_cryosparc_instance_config.tar. It is important to make a copy so that the export file is retained even if thecryosparc_masterinstallation directory is modified or deleted in later steps.Create a new folder for a new recovered database. e.g.
Change
CRYOSPARC_DB_PATHincryosparc_master/config.shto point to the absolute path of the new database folder.Start CryoSPARC with
cryosparcm start. This will result in an empty CryoSPARC instance since the database is empty. You do not need to create users or take any action in the UI at this point.Run the command
What does cryosparcm recover command do?
The recovery process will restore the instance configuration from the exported file, and then attach all projects that were attached at the time the export was created.
Recovery of some projects may be skipped if an error is encountered while attaching it. Projects that are not recovered can be attached to the instance after the recovery process is complete.
Project documents marked as deleted will be skipped.
Project documents marked as detached will be restored to the database so that their records can be viewed in the user interface.
Project documents marked as archived will be saved as detached instead, as they can no longer be unarchived. Unarchiving is no longer possible as the recovered database does not include processing metadata until those metadata are imported to the database during project attachment. Previously archived projects can be restored to the instance by attaching the original project directory after the recovery process is complete.
A project recovery report will be generated and can be used to verify the status of projects in the instance after the recovery process completes.
Example terminal output
Example report
After running the above steps successfully, the instance is ready for use.
Migration of a CryoSPARC instance when the previous database directory is inaccessible
This section describes how to migrate a defunct CryoSPARC instance to a new instance (potentially on a new host) when the previous instance’s database directory has been lost or is inaccessible.
If the previous instance’s database directory is available and intact, then it is simpler to copy the previous database directory to the new instance directly, instead of performing instance recovery. See these instructions for more details in that case.
Regardless of whether a CryoSPARC instance is being migrated using an intact copy of the database or using an instance config export file, one needs to ensure that either
the new
cryosparc_worker/installation paths match records in the database or the config export file orcryosparc_worker_binrecords are adjusted as needed in the CryoSPARC database after migration and before enqueueing jobs.
Prerequisites
Intact project directories mounted on the CryoSPARC master computer at the same path(s) as before the database loss
An instance configuration export archive (e.g.
cryosparc_instance_config_2025_09_29_13h49.tar)copied from the
cryosparc_master/run/directory of the old CryoSPARC installation after the old installation has been shut down permanentlyReliable storage with enough space for the database, allowing for future growth, mounted on the CryoSPARC master computer.
[Optional] Copies of the
config.shfiles from the oldcryosparc_master/andcryosparc_worker/directories. One may refer to these files for custom settings that may continue to apply after migration.
Steps
If needed, install CryoSPARC, but do not start CryoSPARC.
Installation can be skipped if the old installation directories are available on the new CryoSPARC master and worker computers under the same absolute paths as prior to the migration.
[If needed] In case the old cryosparc_worker/ installation is not available on the workers of the new installation, installing worker software under the same path as before removes the need to update scheduler targets’ worker_bin_path.
Follow the steps of the Recovery from a lost database section above.
[If needed] In case the scheduler target paths have changed, update the scheduler target configuration with the correct paths.
[If needed] In case you have custom settings in your original instance
config.shfile that should be kept, copy those custom settings over to the new installation’sconfig.sh.
Last updated