Documentation

Select product

influxdb3 serve

The influxdb3 serve command starts the InfluxDB 3 Enterprise server.

Usage

influxdb3 serve [OPTIONS]

Required Parameters

  • node-id: A unique identifier for your server instance. Must be unique for any hosts sharing the same object store.
  • cluster-id: A unique identifier for your cluster. Must be different from any node-id in your cluster.
  • object-store: Determines where time series data is stored.
  • Other object store parameters depending on the selected object-store type.

--node-id and --cluster-id support alphanumeric strings with optional hyphens.

Global configuration options

Some configuration options (like --num-io-threads) are global and must be specified before the serve command:

influxdb3 --num-io-threads=8 serve --node-id=node0 --cluster-id=cluster0 --verbose

See Global configuration options for the complete list.

Options

Option Description
--admin-token-recovery-http-bind See configuration options
--admin-token-recovery-tcp-listener-file-path See configuration options
--admin-token-file See configuration options
--aws-access-key-id See configuration options
--aws-allow-http See configuration options
--aws-credentials-file See configuration options
--aws-default-region See configuration options
--aws-endpoint See configuration options
--aws-secret-access-key See configuration options
--aws-session-token See configuration options
--aws-skip-signature See configuration options
--azure-allow-http See configuration options
--azure-endpoint See configuration options
--azure-storage-access-key See configuration options
--azure-storage-account See configuration options
--bucket See configuration options
--catalog-sync-interval See configuration options
--cluster-id See configuration options
--compaction-check-interval See configuration options
--compaction-cleanup-wait See configuration options
--compaction-gen2-duration See configuration options
--compaction-max-num-files-per-plan See configuration options
--compaction-multipliers See configuration options
--data-dir See configuration options
--datafusion-config See configuration options
--datafusion-max-parquet-fanout See configuration options
--datafusion-num-threads See configuration options
--datafusion-runtime-disable-lifo-slot Development-only Tokio runtime configuration
--datafusion-runtime-event-interval Development-only Tokio runtime configuration
--datafusion-runtime-global-queue-interval Development-only Tokio runtime configuration
--datafusion-runtime-max-blocking-threads Development-only Tokio runtime configuration
--datafusion-runtime-max-io-events-per-tick Development-only Tokio runtime configuration
--datafusion-runtime-thread-keep-alive Development-only Tokio runtime configuration
--datafusion-runtime-thread-priority Development-only Tokio runtime configuration
--datafusion-runtime-type Development-only Tokio runtime configuration
--datafusion-use-cached-parquet-loader See configuration options
--delete-grace-period See configuration options
--disable-authz See configuration options
--disable-parquet-mem-cache See configuration options
--distinct-cache-eviction-interval See configuration options
--distinct-value-cache-disable-from-history See configuration options
--exec-mem-pool-bytes See configuration options
--force-snapshot-mem-threshold See configuration options
--gen1-duration See configuration options
--gen1-lookback-duration See configuration options
--google-service-account See configuration options
--hard-delete-default-duration See configuration options
-h --help Print help information
--help-all Print detailed help information
--http-bind See configuration options
--last-cache-eviction-interval See configuration options
--last-value-cache-disable-from-history See configuration options
--license-email See configuration options
--license-file See configuration options
--log-destination See configuration options
--log-filter See configuration options
--log-format See configuration options
--max-http-request-size See configuration options
--mode See configuration options
--node-id See configuration options
--node-id-from-env See configuration options
--num-cores See configuration options
--num-datafusion-threads See configuration options
--num-database-limit See configuration options
--num-table-limit See configuration options
--num-total-columns-per-table-limit See configuration options
--object-store See configuration options
--object-store-cache-endpoint See configuration options
--object-store-connection-limit See configuration options
--object-store-http2-max-frame-size See configuration options
--object-store-http2-only See configuration options
--object-store-max-retries See configuration options
--object-store-retry-timeout See configuration options
--package-manager See configuration options
--parquet-mem-cache-prune-interval See configuration options
--parquet-mem-cache-prune-percentage See configuration options
--parquet-mem-cache-query-path-duration See configuration options
--parquet-mem-cache-size See configuration options
--permission-tokens-file See configuration options
--plugin-dir See configuration options
--preemptive-cache-age See configuration options
--query-file-limit See configuration options
--query-log-size See configuration options
--replication-interval See configuration options
--retention-check-interval See configuration options
--snapshotted-wal-files-to-keep See configuration options
--table-index-cache-concurrency-limit See configuration options
--table-index-cache-max-entries See configuration options
--tcp-listener-file-path See configuration options
--telemetry-disable-upload See configuration options
--telemetry-endpoint See configuration options
--tls-cert See configuration options
--tls-key See configuration options
--tls-minimum-version See configuration options
--traces-exporter See configuration options
--traces-exporter-jaeger-agent-host See configuration options
--traces-exporter-jaeger-agent-port See configuration options
--traces-exporter-jaeger-service-name See configuration options
--traces-exporter-jaeger-trace-context-header-name See configuration options
--traces-jaeger-debug-name See configuration options
--traces-jaeger-max-msgs-per-second See configuration options
--traces-jaeger-tags See configuration options
--virtual-env-location See configuration options
--wait-for-running-ingestor See configuration options
--wal-flush-interval See configuration options
--wal-max-write-buffer-size See configuration options
--wal-replay-concurrency-limit See configuration options
--wal-replay-fail-on-error See configuration options
--wal-snapshot-size See configuration options
--without-auth See configuration options

Option environment variables

You can use environment variables to define most influxdb3 serve options. For more information, see Configuration options.

Quick-Start Mode

For development, testing, and home use, you can start InfluxDB 3 Enterprise by running influxdb3 without the serve subcommand or any configuration parameters. The system automatically generates required values:

  • node-id: {hostname}-node (fallback: primary-node)
  • cluster-id: {hostname}-cluster (fallback: primary-cluster)
  • object-store: file
  • data-dir: ~/.influxdb

The system displays warning messages showing the auto-generated identifiers:

Using auto-generated node id: mylaptop-node. For production deployments, explicitly set --node-id
Using auto-generated cluster id: mylaptop-cluster. For production deployments, explicitly set --cluster-id

Quick-start examples

# Zero-config startup
influxdb3

# Override specific defaults
influxdb3 --object-store memory

# Use environment variables to override defaults
INFLUXDB3_NODE_IDENTIFIER_PREFIX=my-node influxdb3

Production deployments

Quick-start mode is designed for development and testing environments. For production deployments, use explicit configuration with the serve subcommand and specify all required parameters as shown in the Examples below.

Configuration precedence: CLI flags > environment variables > auto-generated defaults

For more information about quick-start mode, see Get started.

Examples

In the examples below, replace the following:

  • my-host-01: a unique string that identifies your InfluxDB 3 Enterprise server.
  • my-cluster-01: a unique string that identifies your InfluxDB 3 Enterprise cluster. The value you use must be different from --node-id values in the cluster.

Run the InfluxDB 3 server

influxdb3 serve \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --node-id 
my-host-01
 \
  --cluster-id 
my-cluster-01

Run a server in specific modes

influxdb3 serve \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --node-id 
my-host-01
 \
  --cluster-id 
my-cluster-01
 \
  --plugin-dir ~/.influxdb3/plugins \
  --mode ingest,query,process

Run a server specifically for compacting data

influxdb3 serve \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --node-id 
my-host-01
 \
  --cluster-id 
my-cluster-01
 \
  --mode compact

Run the InfluxDB 3 server with extra verbose logging

influxdb3 serve \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --node-id 
my-host-01
 \
  --cluster-id 
my-cluster-01

  --verbose

Run InfluxDB 3 with debug logging using LOG_FILTER

LOG_FILTER=debug influxdb3 serve \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --node-id 
my-host-01
 \
  --cluster-id 
my-cluster-01

Troubleshooting

Common Issues

  • Error: “cluster-id cannot match any node-id in the cluster”
    Ensure your --cluster-id value is different from all --node-id values in your cluster.

  • Error: “Failed to connect to object store”
    Verify your --object-store setting and ensure all required parameters for that storage type are provided.

  • Permission errors when using S3, Google Cloud, or Azure storage
    Check that your authentication credentials are correct and have sufficient permissions.

Was this page helpful?

Thank you for your feedback!

© 2026 InfluxData, Inc.

What is your InfluxDB 3 Enterprise URL?

Customize your InfluxDB 3 Enterprise URL and we’ll update code examples for you.

  • InfluxDB Cloud
  • InfluxDB OSS or Enterprise
AWS

  • US West (Oregon)

GCP
Azure
Default
Custom

For more information, see InfluxDB Cloud regions or InfluxDB OSS URLs.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

New in InfluxDB 3.8

Key enhancements in InfluxDB 3.8 and the InfluxDB 3 Explorer 1.6.

See the Blog Post

InfluxDB 3.8 is now available for both Core and Enterprise, alongside the 1.6 release of the InfluxDB 3 Explorer UI. This release is focused on operational maturity and making InfluxDB easier to deploy, manage, and run reliably in production.

For more information, check out:

InfluxDB Docker latest tag changing to InfluxDB 3 Core

On May 27, 2026, the latest tag for InfluxDB Docker images will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments.

If using Docker to install and run InfluxDB, the latest tag will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments. For example, if using Docker to run InfluxDB v2, replace the latest version tag with a specific version tag in your Docker pull command–for example:

docker pull influxdb:2