chroma-core/chroma · error · io::Error

bucket {name:?}: capacity and interval_ns must be positive a

Error message

bucket {name:?}: capacity and interval_ns must be positive and their product must fit in u64

What it means

This error is returned by Config::buckets() in rust/mdac-service/src/lib.rs:83 when a configured token-bucket definition fails validation. A bucket's capacity (u32) and interval_ns (u64) must each be strictly positive, and their product (capacity * interval_ns, i.e. the total refill duration) must not overflow u64. The check uses checked_mul, so any overflow or zero value for either field aborts construction of the bucket set with io::ErrorKind::InvalidInput.

Source

Thrown at rust/mdac-service/src/lib.rs:83

            config = config.merge(Yaml::file(path));
        }
        config
            .merge(Env::prefixed("MDAC_"))
            .extract()
            .map_err(Box::new)
    }

    /// Validate all rates and construct every configured bucket with a full allowance.
    pub fn buckets(&self) -> io::Result<Arc<TokenBuckets>> {
        for (name, config) in &self.buckets {
            if config.capacity == 0
                || config.interval_ns == 0
                || config
                    .interval_ns
                    .checked_mul(u64::from(config.capacity))
                    .is_none()
            {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    format!("bucket {name:?}: capacity and interval_ns must be positive and their product must fit in u64"),
                ));
            }
        }
        Ok(Arc::new(TokenBuckets {
            buckets: self
                .buckets
                .iter()
                .map(|(name, config)| {
                    (
                        name.clone(),
                        TokenBucket::new(config.capacity, Duration::from_nanos(config.interval_ns)),
                    )
                })
                .collect(),
        }))
    }

View on GitHub (pinned to a7920e95c1)

Solutions

Inspect the failing bucket name in the error message and fix its capacity to be >= 1 in the YAML config or MDAC_ env override.
Set interval_ns to a positive value; remember it is nanoseconds per token, not total refill time.
Reduce capacity or interval_ns so their product fits in u64 (max ~1.8e19); e.g. prefer smaller capacity with proportionally scaled intervals.
Add pre-startup validation of the buckets config section so misconfiguration is caught before Config::buckets() is called.

Example fix

// before (config.yaml)
buckets:
  api:
    capacity: 0
    interval_ns: 1_000_000_000

// after
buckets:
  api:
    capacity: 10
    interval_ns: 1_000_000_000

Defensive patterns

Strategy: validation

Validate before calling

fn validate_bucket(name: &str, capacity: u32, interval_ns: u64) -> Result<(), String> {
    if capacity == 0 {
        return Err(format!("bucket {name}: capacity must be > 0"));
    }
    if interval_ns == 0 {
        return Err(format!("bucket {name}: interval_ns must be > 0"));
    }
    interval_ns
        .checked_mul(u64::from(capacity))
        .ok_or_else(|| format!("bucket {name}: capacity * interval_ns overflows u64"))?;
    Ok(())
}

Type guard

fn is_valid_bucket(capacity: u32, interval_ns: u64) -> bool {
    capacity > 0
        && interval_ns > 0
        && interval_ns.checked_mul(u64::from(capacity)).is_some()
}

Try / catch

let buckets = config.buckets().map_err(|e| {
    eprintln!("invalid rate-limit bucket config: {e}");
    std::process::exit(2);
});

Prevention

Never set capacity or interval_ns to 0 in bucket YAML or MDAC_ env overrides.
Compute interval_ns as nanoseconds per token; if you think in seconds, multiply by 1_000_000_000 and re-check overflow with capacity.
Keep capacity * interval_ns below u64::MAX (about 1.8e19) when sizing buckets.
Add a unit test that builds Config::buckets() for your production config file in CI.

When it happens

Trigger: Calling Config::buckets() when any entry in self.buckets has capacity == 0, interval_ns == 0, or interval_ns * capacity (as u64) > u64::MAX. Values come from YAML config merged with MDAC_-prefixed environment overrides via figment, so a bad YAML bucket entry or an env var like MDAC_BUCKETS_<NAME>_INTERVAL_NS set to 0 or an enormous number triggers it.

Common situations: Typo in a YAML bucket config leaving capacity unset/0; an environment override setting interval_ns to 0; copy-pasting an interval like 1e18 ns per token with a large capacity so the product overflows u64; converting from a seconds-based config to nanoseconds and multiplying by 1_000_000_000, pushing the product past u64::MAX.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of chroma-core/chroma@a7920e95c1 (2026-09-12). Data as JSON: /api/errors/bfd5c691317d5841. Report an issue: GitHub.