xai-org/x-algorithm · error · ValueError

acks must be 0, 1, or 'all', got {self.acks!r}

Error message

acks must be 0, 1, or 'all', got {self.acks!r}

What it means

The producer config validator whitelists acks to the Kafka-legal values 0, 1, or the string 'all'. Anything else — including the int 2, '1', or -1 — fails with a message echoing the offending value, because aiokafka would otherwise reject or misinterpret it at runtime.

Source

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

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,
            )
        except BaseException:

View on GitHub (pinned to 24c60942c5)

Solutions

  1. Use acks=1 (int) for default durability, acks=0 for fire-and-forget, or acks='all' (exact string) for full replication acks.
  2. If the value comes from an env var, normalize it: int(v) if v.isdigit() else v.
  3. Remove -1 aliases; this library does not map them.

Example fix

# before
cfg = MultiRegionKafkaProducerConfig(clusters={...}, acks=-1)  # ValueError

# after
cfg = MultiRegionKafkaProducerConfig(clusters={...}, acks='all')
Defensive patterns

Strategy: validation

Validate before calling

def norm_acks(v):
    return int(v) if str(v).isdigit() else v
acks = norm_acks(os.environ.get('KAFKA_ACKS', '1'))
assert acks in (0, 1, 'all')
cfg = MultiRegionKafkaProducerConfig(clusters=clusters, acks=acks)

Try / catch

try:
    cfg = MultiRegionKafkaProducerConfig(clusters=c, acks=a)
except ValueError as e:
    if 'acks' in str(e):
        a = 'all'  # safe fallback
        cfg = MultiRegionKafkaProducerConfig(clusters=c, acks=a)
    else:
        raise

Prevention

When it happens

Trigger: MultiRegionKafkaProducerConfig(acks=2), acks='1' (string digit), acks=-1 (old-style alias for all), or a YAML value parsed as the wrong type.

Common situations: Translating Java Kafka configs where acks=-1/acks=all conventions differ; YAML unquoted all being fine but numeric strings like '1' coming from env vars being str not int; copying a config that worked with a different client library.

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 xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/a7672b2f839fca60. Report an issue: GitHub.