§ 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 dfx 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, ask in the Node Provider Matrix channel for help moving it out before removal. 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)

Configure a dfx identity backed by the HSM. The PKCS#11 library path differs by operating system:

# macOS
dfx identity new node-operator-hsm \
  --hsm-key-id 01 \
  --hsm-pkcs11-lib-path /Library/OpenSC/lib/opensc-pkcs11.so

# Linux
dfx identity new node-operator-hsm \
  --hsm-key-id 01 \
  --hsm-pkcs11-lib-path /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

Switch to the HSM identity and supply the PIN:

dfx identity use node-operator-hsm
export DFX_HSM_PIN=<your-hsm-pin>

Call the registry canister to remove the node:

dfx canister --network ic --identity node-operator-hsm \
  call 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:

dfx identity import node_operator node_operator_private_key.pem \
  --storage-mode=plaintext

dfx canister --network ic --identity node_operator \
  call 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