influxdata/influxdb · error · ValidationError

number of buckets in partition template must be in range

Error message

number of buckets in partition template must be in range [{ALLOWED_BUCKET_QUANTITIES:?}), number specified: {0}

What it means

This error is thrown by `InvalidNumberOfBuckets` in the partition template validation of core/data_types. A partition template that includes a Bucket part must specify how many buckets the tag value is hashed into, and that count must be one of the pre-approved `ALLOWED_BUCKET_QUANTITIES` values. The library rejects any other number to bound the number of distinct partitions created in the catalog.

Solutions

Change the bucket count in the Bucket template part to a value listed in `ALLOWED_BUCKET_QUANTITIES` (see core/data_types/src/partition_template.rs).
If you need finer cardinality control, stack multiple allowed bucket parts or combine a Bucket part with TagValue parts instead of using a non-standard count.
If the count comes from user config, validate it against the allowed quantities before constructing the template and return a friendly message.

Example fix

// before
let part = Part::Bucket(7);
// after
let part = Part::Bucket(8); // 8 is in ALLOWED_BUCKET_QUANTITIES

Defensive patterns

Strategy: validation

Validate before calling

const ALLOWED_BUCKET_QUANTITIES: &[u32] = &[1, 2, 4, 8, 16, 32, 64, 128]; // see partition_template.rs
fn valid_bucket_count(n: u32) -> bool { ALLOWED_BUCKET_QUANTITIES.contains(&n) }
if !valid_bucket_count(n) { return Err(format!("bucket count {n} not in {ALLOWED_BUCKET_QUANTITIES:?}")); }

Try / catch

// if constructing dynamically:
match PartitionTemplate::new(parts) {
    Ok(t) => t,
    Err(e) if e.to_string().contains("number of buckets") => {
        eprintln!("bucket count rejected, allowed: {ALLOWED_BUCKET_QUANTITIES:?}");
        return Err(e.into());
    }
    Err(e) => return Err(e.into()),
}

Prevention

Define bucket counts only from the published ALLOWED_BUCKET_QUANTITIES list.
Validate user-supplied bucket counts at config-parse time, before calling the library.
Add a unit test covering every bucket count your tooling can emit.

When it happens

Trigger: Calling the partition-template constructor/validator (e.g. `PartitionTemplate::new` / proto conversion from `template_part::Part::Bucket`) with a bucket count that is not one of the allowed quantities, e.g. `Part::Bucket(7)` when only 1, 2, 4, 8 are allowed.

Common situations: Hand-writing an InfluxDB 3 custom partition template JSON and picking an arbitrary bucket count; generating bucket counts programmatically without checking the allowed list; copying an example with a different bucket count.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/637a0d86f33ee673. Report an issue: GitHub.

Appendix: source

Thrown at core/data_types/src/partition_template.rs:236

    /// provided strftime formatter is invalid.
    ///
    /// [`TimeFormat`]: [`proto::template_part::Part::TimeFormat`]
    #[error("invalid strftime format in partition template: {0}")]
    InvalidStrftime(String),

    /// The partition template defines a [`TagValue`] part or [`Bucket`] part,
    /// but the provided tag name value is invalid.
    ///
    /// [`TagValue`]: [`proto::template_part::Part::TagValue`]
    /// [`Bucket`]: [`proto::template_part::Part::Bucket`]
    #[error("invalid tag name value in partition template: {0}")]
    InvalidTagValue(String),

    /// The partition template defines a [`Bucket`] part, but the provided
    /// number of buckets is invalid.
    ///
    /// [`Bucket`]: [`proto::template_part::Part::Bucket`]
    #[error(
        "number of buckets in partition template must be in range \
        [{ALLOWED_BUCKET_QUANTITIES:?}), number specified: {0}"
    )]
    InvalidNumberOfBuckets(u32),

    /// The partition template defines a [`TagValue`] or [`Bucket`] part
    /// which repeats a tag name used in another [`TagValue`] or [`Bucket`] part.
    /// This is not allowed
    ///
    /// [`TagValue`]: [`proto::template_part::Part::TagValue`]
    /// [`Bucket`]: [`proto::template_part::Part::Bucket`]
    #[error("tag name value cannot be repeated in partition template: {0}")]
    RepeatedTagValue(String),

    /// An attempt to make a new partition template without a [`TimeFormat`]
    /// part has been made. This is not allowed.
    ///
    /// [`TimeFormat`]: [`proto::template_part::Part::TimeFormat`]

View on GitHub (pinned to 06200ef96b)