influxdata/influxdb · error · ValidationError

Custom partition template specified

Error message

Custom partition template specified {specified} parts. Partition templates may have a maximum of {MAXIMUM_NUMBER_OF_TEMPLATE_PARTS} parts.

What it means

This error is returned when a custom partition template specifies more parts than the allowed maximum, `MAXIMUM_NUMBER_OF_TEMPLATE_PARTS`. Partition templates with too many parts create excessive small partitions and degrade performance, so the library enforces an upper bound during validation. The error reports how many parts were specified versus the maximum allowed.

Solutions

  1. Reduce the number of template parts to `MAXIMUM_NUMBER_OF_TEMPLATE_PARTS` or fewer, keeping only the highest-value dimensions
  2. Collapse several low-cardinality tag parts into a single bucket part or combine tags before partitioning
  3. Check the constant value in the current library version and validate user input against it before submitting
  4. For deeply nested time granularity, use fewer strftime parts (e.g., one `%Y-%m-%d` instead of separate year/month/day)

Example fix

// before
let template = PartitionTemplateBuilder::new()
    .add_tag_part("a").add_tag_part("b").add_tag_part("c")
    .add_tag_part("d").add_tag_part("e")
    .build()?; // TooManyParts if > MAXIMUM_NUMBER_OF_TEMPLATE_PARTS
// after
let template = PartitionTemplateBuilder::new()
    .add_tag_part("a").add_tag_part("b") // stay within the max
    .build()?;
Defensive patterns

Strategy: validation

Validate before calling

use crate::partition_template::MAXIMUM_NUMBER_OF_TEMPLATE_PARTS;
fn check_part_count(parts: &[TemplatePart]) -> Result<(), String> {
    if parts.len() > MAXIMUM_NUMBER_OF_TEMPLATE_PARTS {
        return Err(format!("{} parts exceeds max {}", parts.len(), MAXIMUM_NUMBER_OF_TEMPLATE_PARTS));
    }
    Ok(())
}

Type guard

fn within_part_limit(parts: &[TemplatePart]) -> bool {
    parts.len() <= MAXIMUM_NUMBER_OF_TEMPLATE_PARTS
}

Try / catch

let template = builder.build().map_err(|e| match e {
    ValidationError::TooManyParts { specified } => {
        anyhow!("trim template to <= {} parts (got {})", MAXIMUM_NUMBER_OF_TEMPLATE_PARTS, specified)
    }
    other => anyhow!(other),
})?;

Prevention

When it happens

Trigger: Calling `PartitionTemplateBuilder::build()` (or validating a proto template) after adding more parts than `MAXIMUM_NUMBER_OF_TEMPLATE_PARTS`, e.g. many chained `add_tag_part`/`add_strftime_format`/`add_bucket_part` calls, or constructing from a user-supplied parts list exceeding the limit.

Common situations: Users modelling very high-cardinality hierarchies (e.g., tag per dimension) in DDL requests; config-driven template generation that expands every column into a part; porting templates from systems without a part-count limit.

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/5e16b900192ddf4c. Report an issue: GitHub.

Appendix: source

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

    format::{self, Numeric, StrftimeItems},
};
use generated_types::influxdata::iox::partition_template::v1 as proto;
use murmur3::murmur3_32;
use percent_encoding::{AsciiSet, CONTROLS, percent_decode_str};
use schema::TIME_COLUMN_NAME;
use thiserror::Error;

use crate::{MismatchedNumPartsError, PartitionKey, PartitionKeyBuilder};

/// Reasons a user-specified partition template isn't valid.
#[derive(Debug, Error)]
pub enum ValidationError {
    /// The partition template didn't define any parts.
    #[error("Custom partition template must have at least one part")]
    NoParts,

    /// The partition template exceeded the maximum allowed number of parts.
    #[error(
        "Custom partition template specified {specified} parts. \
        Partition templates may have a maximum of {MAXIMUM_NUMBER_OF_TEMPLATE_PARTS} parts."
    )]
    TooManyParts {
        /// The number of template parts that were present in the user-provided custom partition
        /// template.
        specified: usize,
    },

    /// The partition template defines a [`TimeFormat`] part, but the
    /// 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.

View on GitHub (pinned to 06200ef96b)