xai-org/x-algorithm · error · ValueError

Region {region!r} must list at least one broker

Error message

Region {region!r} must list at least one broker

What it means

The producer's _validate validator requires each region in clusters to map to at least one broker address. An empty broker list for any region fails config construction with a message naming the offending region.

Source

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

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:
            results = await asyncio.gather(
                *[self._start_region(region, brokers) for region, brokers in regions],
                return_exceptions=True,

View on GitHub (pinned to 24c60942c5)

Solutions

  1. Fill in real broker addresses for the failing region or delete that region entry.
  2. If brokers are discovered dynamically, fail discovery loudly rather than emitting an empty list.
  3. Add a config lint that every clusters value is a non-empty list of host:port strings.

Example fix

# before
cfg = MultiRegionKafkaProducerConfig(clusters={'us': ['b:9092'], 'eu': []})  # ValueError

# after
cfg = MultiRegionKafkaProducerConfig(clusters={'us': ['b:9092'], 'eu': ['eu-b:9092']})
Defensive patterns

Strategy: validation

Validate before calling

clusters = {r: b for r, b in raw.items() if b}
cfg = MultiRegionKafkaProducerConfig(clusters=clusters)

Try / catch

try:
    cfg = MultiRegionKafkaProducerConfig(clusters=raw)
except ValueError as e:
    logger.error('producer cluster config invalid: %s', e)  # names region
    raise

Prevention

When it happens

Trigger: MultiRegionKafkaProducerConfig with a region like {'us': []}; typically from per-region broker templating or discovery that returned nothing for one region.

Common situations: New region enabled in config before brokers are provisioned; DNS-based broker lists that resolved empty at render time; typo'd region key shadowing the populated one.

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/4d122bc82ce5317a. Report an issue: GitHub.