influxdb3 stop node

The influxdb3 stop node command requests a graceful, two-phase stop of a node in your InfluxDB 3 Enterprise cluster.

When you run this command against a live node:

1. The node is marked as stopping in the catalog.
2. The node completes its stop cascade, then confirms the stop. The cascade drains the node’s WAL tail—the writes buffered in the write-ahead log (WAL) since the last snapshot.
3. The node reads as stopped in the catalog, and its licensed cores are freed for other nodes.

By default, the command waits until the node reaches the stopped state (up to --timeout, default 5m) and exits with a non-zero status if the node does not reach stopped in time. Use --no-wait to return as soon as the stop request is accepted.

Usage

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

Options

Option environment variables

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

Behavior

The node lifecycle is two-phase: stop node marks the node stopping, but the node only reads as stopped after its own stop cascade completes and it confirms the stop.

That cascade is what drains the node’s WAL tail. How the node drains it depends on the storage engine: on the Parquet engine, the node persists the buffered writes to Parquet files; on the upgraded storage engine, it captures them in a WAL snapshot.

• By default, the command polls the node state (from system.nodes) until it reaches stopped, up to --timeout (default 5m).
• If the node does not reach stopped within the timeout, the command prints the last observed state and exits with a non-zero status. The node may be wedged in stopping—for example, if the process died mid-cascade. To recover, follow Recover a crashed node.
• With --no-wait, the command returns after the stop request is accepted. Verify that the node reaches stopped before removing it.
• Other nodes in the cluster see the state change after their catalog sync interval (default 10 seconds).
• The command requires authentication if the server has auth enabled.

Running stop node against a node whose process is already dead cannot drain anything: the catalog still moves the node toward stopped, but the WAL tail remains at risk until the node is restarted. See Recover a crashed node.

Examples

• Stop a node gracefully
• Stop a node without waiting
• Stop a node without confirmation
• Stop a node on a remote server

In the examples below, replace the following:

• NODE_ID: The node identifier of the node to stop
• AUTH_TOKEN: Authentication token with sufficient privileges
• INFLUXDB_HOST: Host URL of the running InfluxDB 3 Enterprise server

Stop a node gracefully

Run stop node against the live node. The command prompts for confirmation, requests the stop, and waits for the node to finish its final flush and confirm the stop:

influxdb3 stop node --node-id 
NODE_ID

After the node reads as stopped, you can remove it from the cluster if you intend to permanently remove it.

Stop a node without waiting

Use --no-wait to return as soon as the stop request is accepted. Verify that the node reaches stopped (for example, with influxdb3 show nodes) before removing it:

influxdb3 stop node --node-id 
NODE_ID
 --no-wait

Stop a node without confirmation

influxdb3 stop node --node-id 
NODE_ID
 --no-confirm

Stop a node on a remote server

influxdb3 stop node \
  --host 
INFLUXDB_HOST
 \
  --node-id 
NODE_ID
 \
  --token 
AUTH_TOKEN

Verify node status

Verify the node state using the influxdb3 show nodes command:

influxdb3 show nodes

A gracefully stopped node appears with state: "stopped" in the output.