Data Repair Tasks

Data Repair Tasks restore missing data when an artifact that exist in storage is not in the database. This state may happen during the recovery process when failing over into another region or when restoring a database backup that was finalized at a different time then the storage.

Configure the task to reconcile blobs created in the last specified number of days; reducing your recovery time.
Recover lost metadata when restoring Nexus Repository from a backup where the database and a blob store are out of sync.

Tasks Renamed in Release 3.84.0

The tasks have been renamed in the Nexus Repository 3.84.0 release in the user interface to the following:

Verify and Repair Data Consistency is now Repair - Data Repair Plan
Execute Plan Data Repair is now Repair - Execute Data Repair Plan

These tasks replace the Reconcile Component Database From Blob Store task for all recovery scenarios. The new tasks are faster and more performant while allowing administrators to target a time range while selecting the blob stores and repositories to prioritize the first. Any tasks configured to use the old reconcile task are removing when upgrading to the Nexus Repository 3.83.0 release or later.

Instructions for Use

Running these tasks may take a significant amount of time; impacting recovery timing. Recovery requires using both tasks; the first to generate recovery plans, followed by the second to execute the generated plans. The API may be used to configure the plans, execute the plans, and audit the results.

Step 1: Configure the Data Repair Plan task

Use the scoping properties to limit the amount of time the task takes to repair the prioritized repositories. This is useful when recovering deleted artifacts.

Select the target blobstores.
Each selected blobstore is analyzed one at a time. Selecting multiple blobstores will increase the time to recover.
Prioritize specific repositories.
All repositories from the blobstore are verified however you may prioritize specific repositories when repairing very large blobstores. This makes artifacts from those repositories available sooner than artifacts from repositories in no particular order.
Set the timespan to verify and repair.
Include a limit on how far back the task looks for missing components based on the time they were added to the repository. This greatly speeds up the time needed to run the task. Set it to the just before the time of the last backup or when the artifacts had been soft deleted.
Manually run the task.
This task must be run manually by the administrator in the UI or using the API to configure and run it.
Running the task creates a plan set to the PLANNED state. The plan is put into the EXECUTED state when finished.
Use the API to view the plan results.
Running the task creates a recovery and results plan to review using the REST API to fetch the specific plan. Results are included in the logs for the task.

Data Repair Plan Task Configuration

Use previously created plans
This option is available when plans have been previously generated from a dry run of the task. Save time by avoiding generating a new plan.
Note
After certain time, previously created plan data may become stale. If the database or blob store state has changed since the plan was generated, some of the actions it specifies may no longer execute as expected.
Blob Store
Select which blob stores and their order to repair.
Note
The default value is set to Always Notify, and the “Keep database records when blob is missing” option is enabled by default. As a result, the generated plan will not delete any database records unless you explicitly disable this checkbox.
For existing tasks created before this option was available, select Keep database records when blob is missing before editing and saving the task.
Repository
Select the repositories and their order to prioritize for repair. All repositories from the selected blob stores are repaired.
Timespan
Limits the task to items whose timestamp falls within the specified duration (days, hours, minutes) or within the specified Start and End Date.
Note
The Timespan is applied in both phases of the task:
- Blob store scan: Uses the blob creation timestamp.
- Database scan: Uses the "added to repository" timestamp of the asset record.

Step 2: Configure the Execute Data Repair Plan task

The summary of the previously ran plans are displayed in the task UI.

Review the previously created plans.
For details of each plan, use the API to fetch a json file of the actions to perform.
Manually run the task.
Running the task puts the plans into the EXECUTED state when finished.
Use the API to view the execution results.
Review the results of the plan execution with the API.

Resolution Table

As backups of the database and the storage occur at different times, they may not be consistent with one another during a recovery event. This task compares the available artifact data to reconcile the available differences in the various possible scenarios between this data.

Three steps are performed when artifacts are added to Nexus Repository: (1) the artifacts binary file is saved to storage, (2) a metadata file about the artifact is stored in the same directory with the binary, and (3) an entry about the artifact is stored in the database. This task resolves the differences between these three data sources.

DB (Database) Row
The artifact's metadata may exists in the database or is missing. This may happen when the artifacts was added after the database backup was complete or when the artifact was restored from a backup after being deleted.
Metadata
The metadata file contains similar data to that which is stored in the database. It contains static information on the artifact binary regardless of where and how it is stored. When soft deleting artifacts, the metadata file and database are updated to indicate that the artifact is to be deleted.
Binary
Artifacts are renamed to match their file hash when stored with some metadata retained on the file itself. When the file is found in storage either the database or metadata files may be used to automatically restore the artifact however when they are not present the reconcile may only report the missing files and repair the database/metadata.

The following table lists the recovery scenarios covered by this task. The numbered scenarios represent the recovery steps performed for every artifact when information is present or missing in the database, component metadata file, and the binary file in storage. These actions are how Nexus Repository resolves the scenario with the available data.

Use the API to view the plan-details for the notify action.

Scenario	DB Row	Metadata	Binary	Default Action
1	Exists	Exists	Exists	No Action
2	Exists	Exists	Missing	Report missing binary
3	Exists	Missing	Exists	Create properties file
4	Exists	Missing	Missing	Report missing binary
5	Missing	Exists	Exists	Create missing row
6	Missing	Exists	Missing	Report missing binary
7	Missing	Missing	Missing	No Action
8a	Exists	Soft Delete	Exists	Remove soft delete flag
8b	Exists	Soft Delete	Exists *	Notify
9	Missing	Soft Delete	Exists	Notify
10	Missing	Missing	Exists	Notify

* In scenario 8a, the artifact hash in database matches the metadata, while in scenario 8b the hash on the artifact differs from the database.

Note

See Accessing Reconciliation Reports section for how to retrieve missing binary details via REST API.

Supported Formats

This task recovers metadata for:

Apt, Docker, Go, Helm, Maven, npm, NuGet, p2, PyPI, R, Raw, RubyGems, Yum

API Reference

The tasks may be configured and run using the following Reconcile Plan API endpoints. See the Swagger interface for the required properties and configuration.

HTTP Method	Endpoint Path	Purpose	Use Case
GET	/v1/plan	Get list of currently available plans	List all currently available reconciliation plans so you can see what plans exist and their status before deciding which to run or delete
POST	/v1/plan	Create reconciliation plans with selected parameters	Create one or more new reconciliation plans with selected parameters (e.g., for specific repositories or data areas) before executing them
PUT	/v1/plan	Execute all non executed reconciliation plans	Execute all reconciliation plans that have been created but not yet executed, in a single operation
DELETE	/v1/plan	Delete all non executed reconciliation plans	Delete all reconciliation plans that have not yet been executed, for example if they were created with incorrect parameters or are no longer needed
GET	/v1/plan/{planId}	Returns details for a specific plan identified by planId (single plan lookup)	Retrieve detailed information for a specific plan using its plan ID
PUT	/v1/plan/{planId}	Execute a reconciliation plan based on its Id	Execute a specific reconciliation plan instead of running all pending plans, allowing targeted verification/repair
DELETE	/v1/plan/{planId}	Delete a reconciliation plan based on its Id	Delete a specific reconciliation plan that you don’t want to execute, while keeping others intact
GET	/v1/plan/details	Returns details for all plans or possibly current/active plans (batch/summary view)	Retrieve an overview of all the actions a specific plan would execute , not including the plan state

Accessing Reconciliation Reports

When using the Repair – Data Repair Plan task, Nexus Repository generates a reconciliation plan that identifies the actions required to repair inconsistencies, such as reporting missing binaries. However, Nexus Repository does not currently provide a dedicated UI page for viewing the detailed reconciliation results. Instead, the full details of a reconciliation plan are available through the REST API.

Note

You do not need to execute the plan to view the actions it contains. As soon as the plan is created, its detailed actions can be retrieved using the API. Execution is only required to apply the changes.

Step 1 – Create a Plan

You can create a reconciliation plan in one of the following ways:

Using the REST API

POST /v1/plan

Using the User Interface

Navigate to Administration > Tasks
Create a task of type: Repair – Data Repair Plan
Run the task

Once created, the plan is stored and available for retrieval via the REST API.

Step 2 – Execute the Plan (Optional)

Execution is not required to view the plan details.

If execution is desired:

Using the REST API

PUT /v1/plan/{planId}

Using the User Interface

Create and run a task of type: Repair – Execute Data Repair Plan

Step 3 – Retrieve the Reconciliation Report

The reconciliation report is accessed via the following endpoints.

List All Plans

GET /v1/plan

Returns available plans with their IDs and states.

Retrieve a Specific Plan

GET /v1/plan/{planId}

This returns the full plan, including metadata, configuration, state, and detailed actions.

Example Response

{
    "id": 1,
    "repository": "raw-hosted",
    "state": "PLANNED",
    "created": "2026-02-11T14:49:39.058+00:00",
    "configuration": {
        ".id": "b3a56bf2-3707-4e73-89e0-8049282e09ab",
        ".name": "Repair - Data Repair Plan",
        ".typeId": "blobstore.planReconciliation",
        ".created": "2026-02-11T09:49:34.847-05:00",
        ".enabled": "true",
        ".exposed": "true",
        ".message": "Uses blobs in a blobstore to restore assets to a repository",
        ".updated": "2026-02-11T09:49:34.847-05:00",
        ".visible": "true",
        ".typeName": "Repair - Data Repair Plan",
        "sinceDays": "2",
        "taskScope": "duration",
        "onlyNotify": "true",
        "sinceHours": "null",
        "planEndDate": "2026-02-11T14:49:39.058536Z",
        ".recoverable": "false",
        "sinceMinutes": "null",
        "blobstoreName": "default,test-group",
        "planStartDate": "2026-02-09T14:49:39.058536Z",
        ".notificationCondition": "FAILURE"
    },
    "details": [
        {
            "id": 1,
            "planId": 1,
            "blobId": "52a85cec-94f6-41a8-bf7c-e2514c9d7140",
            "repository": "raw-hosted",
            "datePathRef": "2026-02-10T20:07Z",
            "path": "2026/02/10/20/07/52a85cec-94f6-41a8-bf7c-e2514c9d7140",
            "action": "Recreate database records from blob metadata (.properties file)",
            "state": "PLANNED",
            "reason": "Found blob in storage without a database record",
            "assetName": "/test/raw-test-file-1.37.zip"
        },
        {
            "id": 2,
            "planId": 1,
            "blobId": "3c4ac807-0d4c-47b6-8e2c-a4310b489d3b",
            "repository": "raw-hosted",
            "datePathRef": "2026-02-10T20:07Z",
            "path": "2026/02/10/20/07/3c4ac807-0d4c-47b6-8e2c-a4310b489d3b",
            "action": "Recreate database records from blob metadata (.properties file)",
            "state": "PLANNED",
            "reason": "Found blob in storage without a database record",
            "assetName": "/test/raw-test-file-1.38.zip"
        }
    ],
    "continuationToken": null
}

Retrieve Only Plan Details

GET /v1/plan/details?planId={planId}

This endpoint returns the detailed actions for the specified plan.

Example Response

{
    "items": [
        {
            "id": 1,
            "planId": 1,
            "blobId": "52a85cec-94f6-41a8-bf7c-e2514c9d7140",
            "repository": "raw-hosted",
            "datePathRef": "2026-02-10T20:07Z",
            "path": "2026/02/10/20/07/52a85cec-94f6-41a8-bf7c-e2514c9d7140",
            "action": "Recreate database records from blob metadata (.properties file)",
            "state": "PLANNED",
            "reason": "Found blob in storage without a database record",
            "assetName": "/test/raw-test-file-1.37.zip"
        },
        {
            "id": 2,
            "planId": 1,
            "blobId": "3c4ac807-0d4c-47b6-8e2c-a4310b489d3b",
            "repository": "raw-hosted",
            "datePathRef": "2026-02-10T20:07Z",
            "path": "2026/02/10/20/07/3c4ac807-0d4c-47b6-8e2c-a4310b489d3b",
            "action": "Recreate database records from blob metadata (.properties file)",
            "state": "PLANNED",
            "reason": "Found blob in storage without a database record",
            "assetName": "/test/raw-test-file-1.38.zip"
        }
    ],
    "continuationToken": null
}

See Recovery Mode documentation. Recovery Mode is not required to run reconciliation tasks, but it is strongly recommended when executing reconciliation plans to help prevent data corruption. It is not necessary when only creating a plan using the Data Repair Plan task without executing it.

Performance Considerations

To speed the recovery of blobs, a new date-based blob store layout was introduced in the 3.83.0 release of Nexus Repository. Prior to this change, blobstores used a vol/chap layout which did not organise the blobs by date. While the new layout is used for blobs added to the repository after upgrading to versions after the 3.83.0 release, blobs that pre-date the upgrade remain in the previous layout.

When you work with data that still uses the legacy vol/chap layout, the Repair - Data Repair Plan task relies on reconciliation log files to identify mismatches. These log files are stored under .../nexus3/blobs/default/reconciliation/. For the configured timespan, the task reads the relevant log files and identifies only those blobs that are recorded there. If a blob exists only as a file on disk and is not referenced in any reconciliation log, it will not be identified by the task. To identify blobs in the legacy layout via reconciliation logs, there must be a file named YYYY-MM-DD in the path nexus3/blobs/default/reconciliation/YYYY-MM-DD.

When the task is run with a timespan to include blobs that predates the upgrade to a version after the 3.83.0 release, the task may take significantly longer to complete as the task must iterate over every blob using the previous layout and check its modification timestamp.

Performance Testing

In terms of functional validation, in all tests executed, there were more than 99.9% of records created in the DB based on the blob files. The 100% is typically not reachable in all cases, as we're triggering a failure and there are a small number of missing records. Some tests reached 100% of the records recovery.

The formats used to test were raw and maven, while the results vary depending on the format, the general pattern of the task execution is similar for all of them.

While the system is back working in less than 20 minutes, the reconciliation task can take further time depending on the number of records missing.
In the Maven case, restoring more than 129K files may take more than 3 hours with a thread pool of 2.
It can take between 13 and 51 milliseconds to restore each row missing from the blob files, this figure mainly depends on the thread pool size parameter. With the parameter set to 8, the time taken for raw assets to be restored can be 3X shorter than when having the parameter set to 2. The format to reconcile has to do with the performance of the task