xai-org/x-algorithm · error · ValueError

`clusters` must contain at least one region

Error message

`clusters` must contain at least one region

What it means

MultiRegionKafkaProducerConfig mirrors the consumer config: a pydantic model_validator rejects an empty clusters mapping because the producer would have nowhere to send records. Construction of the config object itself fails.

Source

Thrown at grox/libs/kafka_cli/multi_region_producer.py:25

from kafka_cli.mtls import create_mtls_ssl_context
from monitor.metrics import Metrics
from pydantic import BaseModel, Field, model_validator

logger = logging.getLogger(__name__)

RETRY_FAILED_REGION_INTERVAL_SEC = 60


class MultiRegionKafkaProducerConfig(BaseModel):
    topic: str
    clusters: dict[str, list[str]]
    acks: int | str = Field(default=1)
    request_timeout_ms: int = Field(default=30000)

    @model_validator(mode="after")
    def _validate(self) -> "MultiRegionKafkaProducerConfig":
        if not self.clusters:
            raise ValueError("`clusters` must contain at least one region")
        for region, brokers in self.clusters.items():
            if not brokers:
                raise ValueError(f"Region {region!r} must list at least one broker")
        if self.acks not in (0, 1, "all"):
            raise ValueError(f"acks must be 0, 1, or 'all', got {self.acks!r}")
        return self


class MultiRegionKafkaProducer:
    def __init__(self, config: MultiRegionKafkaProducerConfig):
        self.config = config
        self.topic: str = config.topic
        self._producers: dict[str, AIOKafkaProducer] = {}
        self._region_retry_task: asyncio.Task | None = None

    async def start(self):
        regions = list(self.config.clusters.items())
        try:

View on GitHub (pinned to 24c60942c5)

Solutions

  1. Provide at least one region with brokers in the producer config.
  2. Fix the templating/config source that yields the empty mapping.
  3. Validate the config at deploy time (e.g. in a helm hook or bootstrap check) so it fails before rollout.

Example fix

# before
cfg = MultiRegionKafkaProducerConfig(clusters={})  # ValueError

# after
cfg = MultiRegionKafkaProducerConfig(clusters={'us-east-1': ['kafka-0:9092']})
Defensive patterns

Strategy: validation

Validate before calling

if not producer_clusters:
    raise SystemExit('producer clusters config is empty')
cfg = MultiRegionKafkaProducerConfig(clusters=producer_clusters)

Try / catch

try:
    cfg = MultiRegionKafkaProducerConfig(**raw)
except ValueError as e:
    logger.error('invalid producer config: %s', e)
    raise

Prevention

When it happens

Trigger: MultiRegionKafkaProducerConfig(clusters={}) or config loaded from a source where the producer's clusters section is missing/empty.

Common situations: Producer and consumer configs generated from the same template and the producer section was forgotten; deploying a producer-only service with a config intended for a different role; empty default after a schema migration.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/a6c8c6db62117993. Report an issue: GitHub.