---
title: Removing a Node From the Registry
slug: removing-node-from-registry
description: 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.
tags:
  - node-provider
  - maintenance
  - runbook
  - registry
date: 2026-05-04
related:
  - node-provider-maintenance
  - node-provider-documentation
  - adding-additional-nodes
  - changing-node-ipv6
---

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](/wiki/node-provider-documentation/) and
the [Node Provider Maintenance Guide](/wiki/node-provider-maintenance/).

## 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](https://dashboard.internetcomputer.org/).
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:

```bash
# 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:

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

Call the registry canister to remove the node:

```bash
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 &mdash; Remove the node (PEM workflow)

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

```bash
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 &mdash; 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](/wiki/node-deployment-gen-2/) (or the
  [Gen-1](/wiki/node-deployment-gen-1/) guide for Gen-1 hardware) for
  a fresh redeployment.

## Related

- [Node Provider Maintenance Guide](/wiki/node-provider-maintenance/) &mdash; the parent runbook.
- [Adding Additional Node Machines to an Existing Allowance](/wiki/adding-additional-nodes/) &mdash; the inverse, when allowance is unused.
- [Changing the IPv6 Addresses of Nodes](/wiki/changing-node-ipv6/) &mdash; uses this procedure as a sub-step.
- [Moving a Node Between Data Centers](/wiki/moving-node-between-data-centers/) &mdash; also uses this procedure.