--- title: influxdb3 stop node description: 'The influxdb3 stop node command gracefully stops a cluster node: the node drains its write-ahead log (WAL) and confirms the stop before it reads as stopped, freeing its licensed cores for other nodes.' url: https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/stop/node/ estimated_tokens: 2156 product: InfluxDB 3 Enterprise version: enterprise publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/stop/node/ date: '2026-08-06T17:50:34+00:00' lastmod: '2026-08-06T17:50:34+00:00' --- 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](/influxdb3/enterprise/reference/internals/durability/#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`](#options), 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. > [!Important] > #### Run this command against the live node—do not kill it first > > `stop node` is how a node drains its[WAL tail](/influxdb3/enterprise/reference/internals/durability/#wal-tail). > If you kill the process first (for example, with `kill -9` or by > force-stopping a container) and run `stop node` afterward, the dead process > cannot drain anything: recently acknowledged writes that were not yet > flushed or snapshotted remain stranded in the WAL, and[removing the node](/influxdb3/enterprise/reference/cli/influxdb3/remove/node/)can then permanently delete them. > If a node has already stopped ungracefully, follow[Recover a crashed node](/influxdb3/enterprise/admin/recover-node/) instead. > [!Note] > Sending the server process a bare `SIGTERM` (without calling `stop node`) > does not force a WAL snapshot on the upgraded storage engine. > Always use `stop node` to stop a cluster node gracefully. ## Usage ```bash influxdb3 stop node [OPTIONS] --node-id ``` ## Options |Option| | Description | |------|-----------------|------------------------------------------------------------------------------------------------------------------| | | `--node-id` | *(Required)* The node ID to stop | | | `--no-confirm` | Skip the confirmation prompt (`--force` is a deprecated alias) | | | `--timeout` |How long to wait for the node to reach `stopped` before giving up—for example: `30s`, `5m`, `1h` (default is `5m`)| | | `--no-wait` | Return as soon as the stop request is accepted instead of waiting for `stopped` | | `-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 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](/influxdb3/enterprise/reference/internals/durability/#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](/influxdb3/enterprise/admin/recover-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 1 second, set with `--catalog-sync-interval`). * 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](/influxdb3/enterprise/reference/internals/durability/#wal-tail)remains at risk until the node is restarted. See [Recover a crashed node](/influxdb3/enterprise/admin/recover-node/). ## Examples * [Stop a node gracefully](#stop-a-node-gracefully) * [Stop a node without waiting](#stop-a-node-without-waiting) * [Stop a node without confirmation](#stop-a-node-without-confirmation) * [Stop a node on a remote server](#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: ```bash influxdb3 stop node --node-id NODE_ID ``` After the node reads as `stopped`, you can[remove it from the cluster](/influxdb3/enterprise/reference/cli/influxdb3/remove/node/)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`](/influxdb3/enterprise/reference/cli/influxdb3/show/nodes/)) before removing it: ```bash influxdb3 stop node --node-id NODE_ID --no-wait ``` ### Stop a node without confirmation ```bash influxdb3 stop node --node-id NODE_ID --no-confirm ``` ### Stop a node on a remote server ```bash 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`](/influxdb3/enterprise/reference/cli/influxdb3/show/nodes/) command: ```bash influxdb3 show nodes ``` A gracefully stopped node appears with `state: "stopped"` in the output. #### Related * [Manage the node lifecycle](/influxdb3/enterprise/admin/node-lifecycle/) * [influxdb3 remove node](/influxdb3/enterprise/reference/cli/influxdb3/remove/node/) * [Recover a crashed node](/influxdb3/enterprise/admin/recover-node/) * [influxdb3 show nodes](/influxdb3/enterprise/reference/cli/influxdb3/show/nodes/) * [influxdb3 serve](/influxdb3/enterprise/reference/cli/influxdb3/serve/) | Option | | Description | | --- | --- | --- | | Option | | Description | | | --node-id | ( Required ) The node ID to stop | | | --no-confirm | Skip the confirmation prompt ( --force is a deprecated alias) | | | --timeout | How long to wait for the node to reach stopped before giving up—for example: 30s , 5m , 1h (default is 5m ) | | | --no-wait | Return as soon as the stop request is accepted instead of waiting for stopped | | -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 | | Environment Variable | Option | | --- | --- | | Environment Variable | Option | | INFLUXDB3_HOST_URL | --host | | INFLUXDB3_AUTH_TOKEN | --token | | INFLUXDB3_TLS_NO_VERIFY | --tls-no-verify |