chroma-core/chroma · error · InvalidConfigurationError

batch_size must be less than or equal to sync_threshold

Error message

batch_size must be less than or equal to sync_threshold

What it means

HNSWConfigurationInternal.configuration_validator (chromadb/api/configuration.py:286) raises InvalidConfigurationError when batch_size exceeds sync_threshold. This cross-parameter constraint exists because HNSW index maintenance batches inserts and syncs the index at sync_threshold; a batch larger than the sync threshold would break the batching/syncing contract. It runs at the end of construction, after individual parameter validation passes.

Source

Thrown at chromadb/api/configuration.py:286

        "sync_threshold": ConfigurationDefinition(
            name="sync_threshold",
            validator=lambda value: isinstance(value, int) and value >= 1,
            is_static=True,
            default_value=1000,
        ),
    }

    @override
    def configuration_validator(self) -> None:
        batch_size = self.parameter_map.get("batch_size")
        sync_threshold = self.parameter_map.get("sync_threshold")

        if (
            batch_size
            and sync_threshold
            and cast(int, batch_size.value) > cast(int, sync_threshold.value)
        ):
            raise InvalidConfigurationError(
                "batch_size must be less than or equal to sync_threshold"
            )

    @classmethod
    def from_legacy_params(cls, params: Dict[str, Any]) -> Self:
        """Returns an HNSWConfiguration from a metadata dict containing legacy HNSW parameters. Used for migration."""

        # We maintain this map to avoid a circular import with HnswParams, and
        # because then names won't change since we intend to deprecate HNSWParams
        # in favor of this type of configuration.
        old_to_new = {
            "hnsw:space": "space",
            "hnsw:construction_ef": "ef_construction",
            "hnsw:search_ef": "ef_search",
            "hnsw:M": "M",
            "hnsw:num_threads": "num_threads",
            "hnsw:resize_factor": "resize_factor",
            "hnsw:batch_size": "batch_size",

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Raise sync_threshold to at least batch_size (or lower batch_size) so the invariant batch_size <= sync_threshold holds
  2. When migrating legacy params, validate and adjust the pair before constructing via from_legacy_params
  3. For very large batches, scale both together, e.g. batch_size=10000 with sync_threshold=10000

Example fix

# before
cfg = HNSWConfigurationInterface(batch_size=2000, sync_threshold=1000)  # InvalidConfigurationError
# after
cfg = HNSWConfigurationInterface(batch_size=1000, sync_threshold=2000)  # invariant holds
Defensive patterns

Strategy: validation

Validate before calling

def validate_hnsw_pair(batch_size: int, sync_threshold: int) -> None:
    if batch_size > sync_threshold:
        raise ValueError(
            f"batch_size ({batch_size}) must be <= sync_threshold ({sync_threshold})"
        )

validate_hnsw_pair(batch_size, sync_threshold)
cfg = HNSWConfigurationInterface(batch_size=batch_size, sync_threshold=sync_threshold)

Try / catch

from chromadb.api.configuration import InvalidConfigurationError

try:
    cfg = HNSWConfigurationInterface(batch_size=b, sync_threshold=s)
except InvalidConfigurationError:
    cfg = HNSWConfigurationInterface(batch_size=min(b, s), sync_threshold=s)  # clamp batch_size

Prevention

When it happens

Trigger: Creating or updating an HNSW configuration with batch_size > sync_threshold, e.g. HNSWConfigurationInterface(batch_size=2000, sync_threshold=1000); migrating legacy collection metadata (hnsw:batch_size / hnsw:sync_threshold) that carries the same violation; loading stored config JSON with an inconsistent pair.

Common situations: Tuning for throughput: raising batch_size without raising sync_threshold; legacy collections created by older versions with looser or no enforcement, now being migrated; mixing values from different tuning guides for the two knobs.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/f72690928c4913ed. Report an issue: GitHub.