Checker Repository Maintenance Tool

Overview

The Checker repository maintenance tool supports several key maintenance tasks for Bloomreach Content repositories. Use this tool to:

• Identify and resolve inconsistencies between the JCR repository and the underlying database.

• Remove orphaned version histories.

• Remove orphaned binary data.

Each task has a dedicated documentation page with detailed instructions. This page describes the Checker tool's technical background, generic setup, usage, and troubleshooting.

Technical Background

The Checker tool operates as a node within an existing repository cluster. When you run the tool, it creates a Jackrabbit storage directory (similar to a standard repository node) and adds a temporary record to the REPOSITORY_LOCAL_REVISIONS database table. The tool removes this record after completing its operation.

Download and Setup

Download

Download the hippo-addon-checker.jar from the Bloomreach Maven repository.

Refer to the release notes to select the correct version for your environment.

Basic Usage

After downloading hippo-addon-checker-<version>.jar, run the tool with:

java -jar hippo-addon-checker-<version>.jar <command>

Use the help command to display available options and usage details.

By default, the JAR includes only the MySQL driver. To connect to a different database, specify the appropriate driver JAR in the classpath:

java -cp "hippo-addon-checker-<version>.jar:<driver>.jar" org.onehippo.cms7.repository.checker.Main <command>

Configuration

Generate Configuration Files

Create a repository configuration file:

java -jar hippo-addon-checker-<version>.jar config > checker-repository.xml

The generated checker-repository.xml contains sample settings for MySQL. Update this file to match your database environment. For configuration examples, see Configure Bloomreach Content for your Database Server.

Create a properties file:

java -jar hippo-addon-checker-<version>.jar props > checker.properties

Edit checker.properties to match your setup.

Specify the repository configuration file:

rep.config=checker-repository.xml

Specify the Jackrabbit file storage location:

rep.home=./checker-storage

Important: Do not use the same storage location as your running Bloomreach Content instance. The Checker runs as a separate node in the cluster and maintains its own local revision state and its own Lucene index in that directory; sharing it with a running instance corrupts both.

Task-Specific Usage

After configuring the Checker tool, follow the instructions in the relevant task documentation:

• Check and fix inconsistencies between the JCR repository and the underlying database.

• Remove orphaned version histories.

• Remove orphaned binary data.

Exporting the Lucene Index

The Checker tool can export the Lucene index from your repository. This is useful for backups or when you need to recreate indexes.

To export the Lucene index:

java -jar hippo-addon-checker-<version>.jar indexexport

The tool saves the exported index as a zip file in the indexexport directory under your repository home directory (as defined by rep.home in checker.properties).

Starting with version 4.0.0, you can use the optional --skip-backup-sync-update parameter to prevent updating the index-backup revision entry (_HIPPO_EXTERNAL_REPO_SYNC_index-backup) during export. Use this option if you want to export the Lucene index without affecting the repository backup synchronization state.

java -jar hippo-addon-checker-<version>.jar indexexport --skip-backup-sync-update

Troubleshooting

If the Checker tool crashes or is stopped before completing its task, the temporary record in the REPOSITORY_LOCAL_REVISIONS table is not removed. To resolve this, rerun the Checker tool and allow it to finish successfully; this will clean up the temporary record.

If the tool continues to crash or cannot complete its task, manually remove the Jackrabbit storage directory and/or delete the corresponding row for the Checker tool in the REPOSITORY_LOCAL_REVISIONS table.

Error Handling

The Checker tool uses standard Unix/Linux return codes:

• 0: Operation completed successfully.

• 1: An error occurred during execution.

You can check the return code in your scripts:

java -jar hippo-addon-checker-<version>.jar indexexport

echo $?

Release Notes

Version	Release Date	Notes	Reference
4.1.0	12 Jun 2026	- Added the ServicingNodeIndexer logger to the console for node indexing progress. - Fixed a hang in the indexexport command caused by a nested monitor lockout.	CMS-18481, CMS-18576
4.0.0	17 Nov 2025	- Added --skip-backup-sync-update parameter for the index export command. - Refactored the Checker tool to use the CMS repository architecture for proper index creation. - Important: The generated repository.xml template (created via the config command) now includes a SearchIndex entry with the FacetedNavigationEngineImpl class, which is required for the Checker tool.	CMS-18188, CMS-18220
3.1.1	24 Oct 2025	Fixed the cleands command to clean up data storage. Note: Do not use this command on versions 3.0.0 and 3.1.0.	CMS-18186
3.1.0	24 Sept 2025	- Added Lucene index export functionality. - Improved error handling.	CMS-18014
3.0.0	9 Sept 2024	- Compatible with XM 16.0 and later. - Requires Java 17.	CMS-15963
2.7.0	20 Feb 2023	- Updated generated repository.xml. - Uses latest MySQL artifacts and driver class name. - Removed check.history.lostnfound option.	CMS-13425
2.6.0	7 Sep 2022	Updated third-party libraries.	CMS-15119
2.5.0	21 Dec 2021	Updated third-party libraries.	CMS-14906
2.4.0	30 Nov 2020	- Compatible with XM 14.3 and later, including XM 15.x. - Runs on Java 8 and Java 11.	CMS-14120