1. CubeBackup Documents
  2. CubeBackup for Microsoft 365 Documents
  3. Tutorials
  4. How to check and repair corrupted or missing snapshot files in CubeBackup for Microsoft 365.

How to check and repair corrupted or missing snapshot files in CubeBackup for Microsoft 365.

CubeBackup may report an error similar to the following when a snapshot file in the data index or backup storage is corrupted or missing:

refCheckRuntime failed: WalkSqlites failed: CacheFileIfNeeded() failed: manager.DownloadFileToCache(…) failed

Use the cbackup checkSnapshots command with the --fix option to check the snapshots and repair the affected files. By default, checkSnapshots checks all organizations and apps. You can also limit it to a particular organization, app, user, or site.

Command syntax and options

cbackup checkSnapshots [-o <organization-id>] [-a <app-type>] [--fix [--force]] [<user-id-or-site-id>]
Option or argument Description
-o <organization-id>, --organization <organization-id> Check only the specified Microsoft 365 organization.
-a <app-type>, --app <app-type> Check only one app. Supported values are drive, mail, calendar, contacts, and site.
<user-id-or-site-id> Check only the specified user or site.
--fix Repair broken snapshots from backup storage and remove snapshots that cannot be recovered. Without this option, the command only checks and reports problems.
--force With --fix, proceed even when fewer than three snapshots are healthy, more than half are broken, or unknown errors are found.

Important: Run the repair without --force first. Use --force only after reviewing the command output or when instructed by CubeBackup support. This option bypasses safeguards that normally prevent repairs or removals when the snapshot set may be unsafe to modify.

Check and repair snapshots


Step 1. Upgrade CubeBackup

Upgrade CubeBackup to V1.2.45 or later before running the command. Refresh or sign in to the CubeBackup web console, then follow the upgrade notification that appears.

Step 2. Stop CubeBackup and repair the snapshots

The CubeBackup service must remain stopped while the command is running. Follow the instructions for your operating system.

SSH into the CubeBackup server and run:

sudo /opt/cubebackup365/bin/cbsrv stop
sudo /opt/cubebackup365/bin/cbackup checkSnapshots --fix

The check may take some time, depending on the number and size of the snapshots. Wait for it to finish and review the output before restarting CubeBackup.

If --fix reports an error like the following, run the command again with the --force option:

Failed to fix snapshots for site '…': … , use –force to delete them. Healthy:4, Broken:1, UnknownErr:1

sudo /opt/cubebackup365/bin/cbackup checkSnapshots --fix --force

The --force option permits repairs and removals when fewer than three snapshots are healthy, unknown errors are found, or more than half of the snapshots are broken. After checkSnapshots completes, start the CubeBackup service:

Open Command Prompt as Administrator and run:

"C:\Program Files\CubeBackup365\bin\cbsrv.exe" stop
"C:\Program Files\CubeBackup365\bin\cbackup.exe" checkSnapshots --fix

The check may take some time, depending on the number and size of the snapshots. Wait for it to finish and review the output before restarting CubeBackup.

If --fix reports an error like the following, run the command again with the --force option:

Failed to fix snapshots for site '…': … , use –force to delete them. Healthy:4, Broken:1, UnknownErr:1

"C:\Program Files\CubeBackup365\bin\cbackup.exe" checkSnapshots --fix --force

The --force option permits repairs and removals when fewer than three snapshots are healthy, unknown errors are found, or more than half of the snapshots are broken. After checkSnapshots completes, start the CubeBackup service:

  1. Stop the regular CubeBackup container. The temporary container must have exclusive access to the original CubeBackup configuration, data index, and backup storage volumes.

  2. Create a temporary container that opens a Bash shell without starting the CubeBackup service. Mount the same volumes and storage paths used by the regular container. For example:

    sudo docker run --rm -it \
 -p 80:80 -p 443:443 \
 -v /var/cubebackup_index:/cubebackup_index \
 ... \
 --mount source=cube365_cfg,target=/opt/cubebackup365/etc \
 ... \
 --name cubebackup-check-snapshots \
 cubebackup/cube365:1.2.45 \
 bash

    Replace the example volume mounts and image tag with those used by your regular CubeBackup container.

    If you use Docker Compose, you can create the temporary container from the service defined in your Compose file instead:

    docker compose run --rm --entrypoint /bin/bash cubebackup

    Replace cubebackup with the service name in your Compose file.

  3. Inside the temporary container, run:

    /opt/cubebackup365/bin/cbackup checkSnapshots --fix

    The check may take some time, depending on the number and size of the snapshots. Wait for it to finish and review the output.

    If --fix reports an error like the following, run the command again with the --force option:

    Failed to fix snapshots for site '…': … , use –force to delete them. Healthy:4, Broken:1, UnknownErr:1

     /opt/cubebackup365/bin/cbackup checkSnapshots --fix --force

  4. After checkSnapshots completes successfully, type exit to leave the temporary container. Because the container was created with --rm, Docker removes it automatically.

  5. Start the regular CubeBackup container with its original volumes mounted.

Step 3. Run and verify a backup

  1. Sign in to the CubeBackup web console.
  2. On the OVERVIEW page, click Backup now.
  3. After the backup completes, check the backup result and confirm that the error no longer appears.

If the error persists, contact [email protected] and include the error message and the output from the checkSnapshots command.

Check a smaller scope

If the error identifies the affected organization, app, user, or site, you can limit the check instead of scanning every snapshot. Add the appropriate options to the checkSnapshots command shown above. For example:

cbackup checkSnapshots --organization <organization-id> --app site --fix <site-id>

The scope options can also be used without --fix to inspect the affected snapshots without modifying them:

cbackup checkSnapshots --organization <organization-id> --app mail <user-id>