influxdb3 remove node

The influxdb3 remove node command permanently removes a stopped node from your InfluxDB 3 Enterprise cluster. The cluster drains the node’s data (up to its final snapshot) before the catalog entry and the node’s object-store file paths are purged.

Usage

influxdb3 remove node [OPTIONS] --node-id <
NODE_ID
>

Options

Option environment variables

You can use the following environment variables to set command options:

Behavior

When you remove a node:

1. The command verifies the node is stopped and marks it removing in the catalog.
2. The cluster drains the node’s data up to the node’s final snapshot.
3. The node’s catalog entry and object-store file paths are purged.

Removal permanently deletes the node’s object-store file paths, including its WAL files. Any acknowledged writes that were not covered by the node’s final snapshot are deleted with them. That is why the node must complete a graceful stop first.

Removal is refused if unsnapshotted WAL remains (upgraded engine)

On clusters that have fully adopted the upgraded storage engine (the default for new clusters), InfluxDB 3 Enterprise refuses (HTTP 409) to remove a stopped node that still has an unsnapshotted WAL tail:

node 'NODE_ID' has unsnapshotted WAL (wal file N, snapshotted through M);
restart the node so it snapshots the tail, or force the removal (set
force_finalize=true, or pass --force-finalize on the CLI) to remove it and
lose the unsnapshotted writes

To resolve this safely, follow Recover a crashed node: restart the node with the same --node-id, stop it gracefully so it snapshots the tail, and then remove it.

Force removal of a node that did not shut down cleanly

If remove node fails without --force-finalize, the node never finished stopping—its process is gone and never confirmed a clean stop. --force-finalize removes it anyway.

This can lose data: recently acknowledged writes the node had not yet captured in a snapshot are deleted with it. If the node had finished snapshotting and only failed to report a clean stop, nothing is lost.

Prefer the safe path first: restart the node with the same --node-id, let it shut down cleanly, and remove it again. See Recover a crashed node. Use --force-finalize only when the node cannot be brought back and you accept the possible loss.

Examples

• Remove a stopped node
• Remove a node without confirmation
• Force removal of a node that cannot be recovered

In the examples below, replace the following:

• NODE_ID: The node identifier of the node to remove
• AUTH_TOKEN: Authentication token with sufficient privileges

Remove a stopped node

First stop the node gracefully, then remove it:

# Stop the node and wait for it to reach the stopped state
influxdb3 stop node --node-id 
NODE_ID

# Remove the stopped node from the cluster
influxdb3 remove node --node-id 
NODE_ID

The command prompts for confirmation.

Remove a node without confirmation

influxdb3 remove node --node-id 
NODE_ID
 --no-confirm

Force removal of a node that cannot be recovered

Only use --force-finalize after attempting crash recovery, when the node cannot be brought back and you accept the possible loss of unsnapshotted writes:

influxdb3 remove node --node-id 
NODE_ID
 --force-finalize