Skip to content
DFINITYAsk AIQuick start
§ Wiki · Wiki entry

Removing a Node From the Registry

How to remove a node's record from the registry when its allowance is full and the underlying machine has been hardware-replaced or retired.

·May 4, 2026·3 min read

A node operator record permits a fixed number of node machines — the node allowance. Redeploying an existing machine keeps the same node ID, because the IPv6 address derives from hardware that has not changed. But when a motherboard, NIC, or HSM is replaced, the new machine derives a fresh IPv6 address and is treated as a new node. If the operator record is already at its allowance, the old node ID has to be removed before the new one can be onboarded.

For the role context, see Node Provider Documentation and the Node Provider Maintenance Guide.

Prerequisites

  • The node must not be active in any subnet.
  • A workstation with icp installed and IPv6 connectivity to the Internet Computer.
  • Either the physical HSM that signed the original node operator record, or the node_operator_private_key.pem file used in HSM-less onboarding.
Warning

Removing a node from the registry is destructive. The node ID is gone after the call, and the machine cannot rejoin under the same ID without re-onboarding. Confirm the node is not in any subnet before proceeding.

Step 1 — Confirm the node is unassigned

Check the node's status on the Internet Computer Dashboard. The node must be unassigned (not part of any subnet). If it is still in a subnet, take it out first: with a direct node swap if you have an unassigned node in the same data center, otherwise by NNS proposal (see Setting Up a Neuron for NNS Proposals), or ask in the Node Provider Matrix channel for help. As a last resort, physically powering the node off works — but tell the channel first so the subnet's other operators know what to expect.

Step 2 — Retrieve the operator key

If the node operator record was created with a physical HSM, retrieve that HSM from the data center. Skip this step if you onboarded with a PEM file.

Step 3a — Remove the node (HSM workflow)

Link an icp identity to the HSM. The PKCS#11 library path differs by operating system:

# macOS
icp identity link hsm node-operator-hsm \
  --key-id 01 \
  --pkcs11-module /Library/OpenSC/lib/opensc-pkcs11.so

# Linux
icp identity link hsm node-operator-hsm \
  --key-id 01 \
  --pkcs11-module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

Call the registry canister to remove the node, entering the HSM PIN when prompted:

icp canister call -n ic --identity node-operator-hsm \
  rwlgt-iiaaa-aaaaa-aaaaa-cai remove_node_directly \
  '(record { node_id = principal "YOUR-NODE-ID" })'

Step 3b — Remove the node (PEM workflow)

If the operator record was created without an HSM, import the PEM file and call the same method:

icp identity import --storage plaintext \
  --from-pem node_operator_private_key.pem node_operator

icp canister call -n ic --identity node_operator \
  rwlgt-iiaaa-aaaaa-aaaaa-cai remove_node_directly \
  '(record { node_id = principal "NODE_ID" })'

The registry canister ID rwlgt-iiaaa-aaaaa-aaaaa-cai is the same in both flows.

Step 4 — Re-register, if applicable

What happens next depends on why the node was removed:

  • Healthy node, no hardware change. Reinsert the HSM (if used) and reboot. The node rejoins under its original node ID.
  • Hardware was replaced, or the node had unresolved problems. Treat the machine as new. Follow the Gen-2 Node Deployment Guide (or the Gen-1 guide for Gen-1 hardware) for a fresh redeployment.

Related