influxdata/influxdb · error · anyhow::Error

You've incorrectly specified a cluster-id for InfluxDB 3 Cor

Error message

You've incorrectly specified a cluster-id for InfluxDB 3 Core OSS.

Cluster-id is an InfluxDB 3 Enterprise parameter. 
Did you install Core in an upgrade or run Core by mistake?

Remove --cluster-id to run InfluxDB 3 Core OSS.

What it means

In InfluxDB 3 Core OSS, the --cluster-id CLI argument is wired to a clap value_parser (fail_cluster_id) that always returns Err. cluster-id is an Enterprise-only option; historically users who installed Core while thinking they had Enterprise passed --cluster-id and got clap's confusing 'unexpected argument' error, so Core ships this custom, self-explanatory message instead. The error is emitted at argument parsing time, before the server starts.

Source

Thrown at influxdb3/src/commands/serve.rs:694

    /// the catalog.
    #[clap(
        long = "delete-grace-period",
        env = "INFLUXDB3_DELETE_GRACE_PERIOD",
        default_value = "24h",
        action
    )]
    pub delete_grace_period: humantime::Duration,

    /// The cluster-id is an enterprise config option to identify nodes belonging to the same cluster.
    /// Core OSS is single node only. We've seen folks install Core OSS thinking they installed Enterprise.
    /// They use --cluster-id and get the error `unexpected argument` which is confusing. So we generate
    /// a custom error message if they use this arg.
    #[clap(long = "cluster-id", value_parser=fail_cluster_id)]
    pub cluster_id: Option<String>,
}

pub fn fail_cluster_id(_: &str) -> Result<String, anyhow::Error> {
    Err(anyhow::anyhow!(
        "You've incorrectly specified a cluster-id for InfluxDB 3 Core OSS.\n\nCluster-id is an InfluxDB 3 Enterprise parameter. \
    \nDid you install Core in an upgrade or run Core by mistake?\n\nRemove --cluster-id to run InfluxDB 3 Core OSS."
    ))
}

#[derive(Clone, Debug, clap::Args)]
#[group(required = true)]
pub struct NodeId {
    /// The node identifier used as a prefix in all object store file paths. This should be unique
    /// for any InfluxDB 3 Core servers that share the same object store configuration, i.e., the
    /// same bucket.
    #[clap(
        long = "node-id",
        // TODO: deprecate this alias in future version
        alias = "host-id",
        env = "INFLUXDB3_NODE_ID",
        group = "node_id",
        action

View on GitHub (pinned to d28e26e048)

Solutions

1. Remove --cluster-id from the command line / service definition and restart — Core OSS is single-node
2. Verify which edition you run: `influxdb3 --version`
3. If you actually need clustering, install InfluxDB 3 Enterprise instead of Core OSS
4. Audit systemd units, Helm values, and wrapper scripts for leftover Enterprise-only flags

Example fix

# before
influxdb3 serve --node-id n1 --cluster-id my-cluster --object-store file:///data
# -> You've incorrectly specified a cluster-id for InfluxDB 3 Core OSS.

# after
influxdb3 serve --node-id n1 --object-store file:///data

# strip Enterprise-only flags before invoking a Core OSS binary
case "$(influxdb3 --version)" in
  *Enterprise*) ARGS+=("--cluster-id" "$CLUSTER_ID") ;;
  *) echo "Core OSS: dropping --cluster-id" ;;
esac
influxdb3 serve "${ARGS[@]}"

influxdb3 serve "$@" || { echo "serve failed — check for edition-specific flags like --cluster-id" >&2; exit 1; }

When it happens

Trigger: Running `influxdb3 serve --cluster-id <value> ...` on a Core OSS binary. Any presence of the flag triggers the failure regardless of the value passed, because the parser function ignores its input and always errors.

Common situations: Followed Enterprise documentation against a Core binary; downgraded from Enterprise to Core but reused old systemd/Kubernetes manifests or scripts; CI pipelines written for Enterprise pointed at a Core image.

Related errors

• must be formatted as "key=value"
• No plugin directory configured
• token creation to return full token info
• Measurement name cannot contain spaces
• {key_type} key cannot be empty

AI-assisted analysis of influxdata/influxdb@d28e26e048 (2026-08-16). Data as JSON: /api/errors/f9430ddd3e7c3c86. Report an issue: GitHub.