---
title: Swapping a Node in a Subnet
slug: swapping-nodes-in-subnets
description: Replace a poorly performing assigned node with an unassigned node owned by the same operator using swap-node-in-subnet-directly — no NNS proposal required.
tags:
  - node-provider
  - maintenance
  - runbook
  - registry
  - subnets
date: 2026-07-22
related:
  - node-provider-maintenance
  - moving-node-between-data-centers
  - removing-node-from-registry
  - adding-additional-nodes
---

A node assigned to a subnet does useful work and earns rewards; an
unassigned node sits idle and earns nothing. When an assigned node
needs maintenance, node swapping lets you move an unassigned node
— owned by the same node operator, in the same data center
— into the subnet in its place. The subnet keeps its capacity
while you service the machine, and because the swap is a direct
registry call it needs no NNS proposal.

> [!WARNING]
> Do not power the old node off until it has gracefully left the
> subnet. A node that disappears before completing its graceful
> departure looks malicious to consensus, which can trigger a
> rewards penalty. Wait for the log confirmation in step 5 before
> starting any maintenance.

## Before you start

Both nodes have to belong to the same principals and location:

- The **old node** is currently assigned to a subnet.
- The **new node** is unassigned (its subnet shows `-` on the
  dashboard).
- Both nodes share the same node provider, the same node operator,
  and the same data center.

The swap is also rate limited, to protect subnet stability:

- The subnet the old node belongs to must not have had a swap in
  the last **4 hours**.
- You must not have swapped a node on that same subnet in the last
  **24 hours**.

## Procedure

### Step 1 — Locate the assigned node

On the [IC Dashboard](https://dashboard.internetcomputer.org/) find
the assigned node you want to take out of service and note its
node ID (principal).

### Step 2 — Find an unassigned replacement

Identify an unassigned node in the same data center — one
whose subnet column shows `-` — and note its node ID. This is
the node that will take the old node's place in the subnet.

### Step 3 — Set up authentication

Define an `AUTH` array with the node operator key that owns both
nodes. Use a PEM key file:

```bash
AUTH=(
  "--secret-key-pem"
  <path-to-key-pem>
)
```

or an HSM:

```bash
AUTH=(
  "--use-hsm"
  "--slot"
  <hsm-key-slot>
  "--key-id"
  <hsm-key-id>
  "--pin"
  <hsm-pin>
)
```

### Step 4 &mdash; Execute the swap

Run `swap-node-in-subnet-directly`, passing the old node ID from
step 1 and the new node ID from step 2:

```bash
ic-admin --nns-urls https://ic0.app ${AUTH[@]} swap-node-in-subnet-directly \
    --old-node-id <principal-from-step-1> \
    --new-node-id <principal-from-step-2>
```

### Step 5 &mdash; Wait for the graceful departure

The old node takes roughly **15&ndash;20 minutes** to leave the
subnet cleanly. Watch its logs for the two confirmations, in order:

- `Node started leaving subnet`
- `Node gracefully left a subnet`

### Step 6 &mdash; Perform maintenance

Only once the second log line has appeared is the old node fully
out of the subnet. It is now safe to power it off and carry out
whatever maintenance you had planned.

## Related

- [Node Provider Maintenance Guide](/wiki/node-provider-maintenance/) &mdash; the parent runbook.
- [Moving a Node Between Data Centers](/wiki/moving-node-between-data-centers/) &mdash; when the machine has to physically relocate rather than just leave a subnet.
- [Removing a Node From the Registry](/wiki/removing-node-from-registry/) &mdash; retiring a node entirely.
- [Adding Additional Node Machines to an Existing Allowance](/wiki/adding-additional-nodes/) &mdash; bringing the spare capacity online in the first place.