Data Repair Tasks

Known Issue in Sonatype Nexus Repository 3.83.0 - 3.89.1

There is an issue in Sonatype Nexus Repository 3.83.0 - 3.89.1 where running the Verify and Repair or Data Repair Plan tasks can incorrectly delete valid assets, leading to potential data loss.

This issue is fixed in version 3.90.0.

Upgrade to version 3.90.0 before running the Verify and Repair or Data Repair Plan tasks.

These tasks restore missing data when an artifact that exists 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 than 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 first. Any tasks configured to use the old reconcile task are removed 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.

1. Select the target blobstores.

   Each selected blobstore is analyzed one at a time. Selecting multiple blobstores will increase the time to recover.

2. 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.

3. 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 just before the time of the last backup or when the artifacts had been soft deleted.

4. 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.

5. 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 a 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.

• 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 is displayed in the task UI.

1. Review the previously created plans.

   For details of each plan, use the API to fetch a json file of the actions to perform.

2. Manually run the task.

   Running the task puts the plans into the EXECUTED state when finished.

3. 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 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 exist in the database or be missing. This may happen when the artifacts were 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.

* In scenario 8a, the artifact hash in the 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.

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

1. Navigate to Administration > Tasks
2. Create a task of type: Repair – Data Repair Plan
3. 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 organize 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 predate 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.

• 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.