Recover from a broken version history

Inconsistent version history can cause malfunction of many CQ operations, including replication, version restoration, and content package installation.

If a version history is broken, you see the exception org.apache.jackrabbit.core.state.NoSuchItemStateException in the log files. And, you see the same thing in the stack trace classes from the package org.apache.jackrabbit.core.version.

Solution

Use system parameter "org.apache.jackrabbit.version.recovery:"

To apply the parameter, do the following:

1. Install the latest CRX2.2 hot fix. You can request the latest CRX hot fix by submitting a support ticket. Follow the hot fix installation instructions and make sure to restart CQ after installing it.
   
2. Stop CQ/CRX.
3. Add the jvm parameter to the startup script: -Dorg.apache.jackrabbit.version.recovery=true
4. Start CQ/CRX.
5. Check the java process status (for example, ps -ef | grep java) to verify that the new parameter is used.

When enabled, this feature looks for all versionable nodes in the repository, and checks whether the respective version history exists.

If it is not the case, the recovery procedure removes broken reference to the version store. In particular mix:versionable mixin, and properties jcr:versionHistory, jcr:baseVersion, jcr:predecessors and jcr:isCheckedOut. It enables the repository to create new version graph for the node, the time it's required.

If the nodes that are missing are at the root level, the version workspace inconsistencies are not repairable. In that case, it's necessary to start from a new fresh version dataset. Your only chance to get back previous data from the version is to use a backup. Then, you can use the package once the version is restored.   If you have to remove the version folder (which is automatically re-created on startup), one important content to have is your workflow mode. Then, after restarting (with the above jvm parameter), you can install a package that sets the workflows model back into the version. Any workflow instances that aren't completed can't process further as the version information is linked to the workflow instance. (See the related property in the workflow instance node.) If that model version is missing, it cannot continue to process it (it's necessary to fix it manually).   Before completing the steps below, make sure that all workflows are completed. (If you have a running instance, it requires extra actions with a custom script to reset the workflow instance model version reference to the new one).

1. Stop the instance.
2. Delete the version folder and repository/repository/index folder.
3. (Optional) Add consistency/check fix in the crx.default workspace.xml for the Tar Persistence Manager data.
4. Add -Dorg.apache.jackrabbit.version.recovery=true
5. Start the instance (it can take several hours or days depending your data size and I/O performances, so consider testing on a copy first.
   
6. When the instance is ready, create a package from /etc/workflow/models.
7. Delete the /etc/worflow/models (using CRXDE or CRX Explorer).
8. Install the package you just created over to re-create the workflow models.

Note: Starting in CRX 2.2, the parameter described in the following article helps avoid inconsistencies.