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.
Stop the node gracefully before removing it
A node must be stopped before it can be removed.
Use influxdb3 stop node
against the live node and wait for it to reach stopped—the graceful stop
is what drains the node’s
write-ahead log (WAL) tail.
A node stuck in stopping (for example, because the process was killed
mid-stop or was already dead) cannot be removed normally.
To recover such a node safely, follow
Recover a crashed node.
Usage
influxdb3 remove node [OPTIONS] --node-id <NODE_ID>Options
| Option | Description | |
|---|---|---|
--node-id | (Required) The node ID to remove | |
--no-confirm | Skip the confirmation prompt | |
--force-finalize | Force removal of a node that did not shut down cleanly–this can lose data (see Force removal) | |
-H | --host | Host URL of the running InfluxDB 3 Enterprise server (default is http://127.0.0.1:8181) |
--token | Authentication token | |
--tls-ca | Path to a custom TLS certificate authority (for testing or self-signed certificates) | |
--tls-no-verify | Disable TLS certificate verification (Not recommended in production, useful for self-signed certificates) | |
-h | --help | Print help information |
Option environment variables
You can use the following environment variables to set command options:
| Environment Variable | Option |
|---|---|
INFLUXDB3_HOST_URL | --host |
INFLUXDB3_AUTH_TOKEN | --token |
INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify |
Behavior
When you remove a node:
- The command verifies the node is
stoppedand marks itremovingin the catalog. - The cluster drains the node’s data up to the node’s final snapshot.
- 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 writesTo 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.
This safeguard applies only to clusters that have fully adopted the
upgraded storage engine (new clusters, or after the storage engine upgrade
completes).
Parquet clusters and clusters still mid-upgrade are not guarded.
On those clusters, a graceful
stop node before
removal is the only protection against losing the
WAL tail.
To determine which engine your cluster runs, start with how it was created:
new clusters on InfluxDB 3 Enterprise 3.11+ default to the upgraded storage
engine, and clusters that started on 3.10 or earlier keep the Parquet engine
until you restart them with --upgrade-pacha-tree.
If you started a storage engine upgrade, confirm it finished—query
system.upgrade_parquet_node and check that every node reports completed.
See Query system data.
For more information about the upgraded storage engine, see Storage engine.
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 removeAUTH_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_IDThe command prompts for confirmation.
Remove a node without confirmation
influxdb3 remove node --node-id NODE_ID --no-confirmForce 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-finalizeWas this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB 3 Enterprise and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support. Customers using a trial license can email trial@influxdata.com for assistance.