Skip to main content

How to reset node and deployment IDs after cloning a Nexus Repository 3 H2 based instance

Updated

Summary

When a Nexus Repository 3 instance using the embedded H2 database is cloned (for example, to create a test or proof-of-value environment copy of production), the clone may retain the same internal node_id and deployment_id as the original. This article explains why that matters, how to confirm whether it affects you, and an H2-based approach that can be used to force a new deployment identity on the cloned (non‑production) instance.

Explanation

Nexus Repository 3 uses two internal identifiers:

  • Node ID – uniquely identifies a single running process (instance) of Nexus Repository.
  • Deployment ID – uniquely identifies the shared component and asset database content used by a deployment.

In a simple, single-node deployment, these two values are usually the same. In clustered or HA deployments, multiple nodes share the same deployment ID but have different node IDs. The deployment ID is used by features such as Repository Health Check (RHC), malware banner reporting, Repository Firewall / IQ integration, and blob store metrics.

If a database is cloned from one instance to another (for example, copying a production H2 database file to a test environment), the cloned instance will initially have the same deployment ID and often the same node ID as the original. This can cause the two instances to appear as the same deployment to external services and can lead to confusing or incorrect health and malware results being associated with the wrong instance.

Symptoms and impact

You are likely affected if all of the following are true:

  • You run Nexus Repository 3 with the embedded H2 database.
  • You have created a second instance by copying the data directory (including db/nexus.mv.db) from an existing instance.
  • Both instances may be running at the same time (for example, production and a test or PoV clone).

Typical symptoms can include:

  • The test instance and production instance show the same deployment-id in System > Support > System Information.
  • Repository Health Check (RHC) or malware banner counts appear to be “shared” or overwritten between environments, or do not clearly reflect which environment the results belong to.
  • When attempting to run RHC tasks, you may see log messages similar to: 
    java.lang.RuntimeException: Deployment id is absent.

When two instances share a deployment ID, our external services may treat them as the same deployment, causing results (for example, malware counts) from one instance to affect the other.

How to confirm the issue

To check whether two instances are sharing the same deployment ID:

  1. In each Nexus Repository instance, sign in as an administrator.
  2. Navigate to Administration > Support > System Information.
    Locate the nexus-node section and note the values for node-id and deployment-id.
  3. On some versions, System Information has been removed. In that case, the Node ID can be found in the UI by going to System -> Capabilities -> Node Identity.

If two different instances show the same node-id,  they are likely sharing a deployment identity and may interfere with each other’s RHC and malware reporting. In many cloned H2 scenarios, the node-id may also match.

Approach to reset node and deployment IDs on a cloned H2 test instance

The following approach is intended for non‑production, H2‑backed test or PoV instances cloned from another instance. The goal is to give the cloned instance a new internal identity so it no longer shares a deployment ID with the original.

Important notes and limitations:

  • Always take a full backup of the cloned instance’s data directory (especially the H2 database file) before making any changes.
  • This article focuses on H2-based test instances; PostgreSQL-backed deployments use SQL directly against PostgreSQL and follow a similar concept but different tooling.
  • We have observed that some combinations of Nexus Repository version and H2 changes can cause RHC tasks to log Deployment id is absent errors if the deployment ID is missing or not initialized correctly. If you see persistent errors after following these steps, licensed customers should contact Sonatype Support for guidance specific to your version.
  • Do not use this approach on a production instance without a clear plan for the impact on Firewall, IQ, and RHC data, because changing the deployment ID will disconnect that instance from any existing external reports linked to the old identity.

High-level procedure

  1. Stop the cloned (test) Nexus Repository instance.
  2. Back up the H2 database.
    • On the test instance host, go to the Nexus data directory $NEXUS_DATA/db.
    • Copy the H2 file, for example: 
      cp nexus.mv.db nexus.mv.db.bak
  3. Back up the node keystore file.
    • This file influences the node ID; back it up so you can restore it if needed: 
      mv $NEXUS_DATA/keystores/node/private.ks $NEXUS_DATA/keystores/node/private.ks.bak
  4. Open the H2 database console against the stopped instance’s DB file.
    • Download the appropriate H2 console JAR for your Nexus version (for example, for recent versions a console JAR is available from our public tooling).
    • From $NEXUS_DATA/db, run: 
      java -jar ./h2-console_v232.jar ./nexus.mv.db
    • This should give you an H2 SQL console connected to the Nexus database while Nexus is stopped.

  5. Reset the node and deployment identifiers inside H2.

    At the H2 SQL prompt, run commands that remove the old IDs and insert a new randomly generated one. One tested pattern is:

    • Delete existing identifiers: 
      DELETE FROM node_id;
      DELETE FROM deployment_id;
    • Insert a new random node ID (using H2’s RANDOM_UUID() function) and copy it into the deployment ID: 
      INSERT INTO node_id (id, node_id) VALUES (1, RANDOM_UUID());
      INSERT INTO deployment_id (id, deployment_id) SELECT 1, node_id FROM node_id;
    • Optionally verify: 
      SELECT 'node_id' AS table_name, node_id FROM node_id UNION ALL SELECT 'deployment_id' AS table_name, deployment_id FROM deployment_id;

    This ensures that both node_id and deployment_id tables contain a new UUID that no longer matches the original instance.

  6. Exit the H2 console.
    • Type exit at the prompt, or close the console, to ensure all changes are committed.
  7. Start the cloned Nexus Repository instance.
    • On startup, Nexus reads the updated node and deployment IDs from the database. Because private.ks was moved aside, the instance will not try to reuse the old on-disk node ID.
    • After startup, check Administration > Support > System Information and confirm that:
      • The deployment-id is now different from the original (production) instance.
      • The instance starts and operates normally.

After resetting the IDs

Once the cloned instance has its own unique deployment ID:

  • Repository Health Check and malware banner information should no longer interfere with the original instance.
  • If the instance is connected to IQ / Firewall, it will appear as a separate repository manager in IQ and will build a distinct set of reports.

If you still see log entries such as java.lang.RuntimeException: Deployment id is absent for RHC tasks after following these steps, this specific behavior can vary between Nexus Repository versions and is not fully defined in our current public documentation. In that case, we recommend opening a support case with your logs and configuration so we can provide version-specific guidance.

Related articles