headroomlabs-ai/headroom · error · RolloutConfigurationError

invalid rollout worker field {field!r}

Error message

invalid rollout worker field {field!r}

What it means

Raised inside from_internal_dict()'s names() helper when one of the four feature-name list fields ('explicit_requested', 'explicit_disabled', 'legacy_requested', 'legacy_disabled') is not a list of strings. The message names the offending field so you can pinpoint which key is malformed.

Source

Thrown at headroom/rollout.py:303

    def from_internal_dict(cls, value: Mapping[str, object]) -> RolloutSnapshot:
        """Validate and restore a snapshot serialized for worker handoff."""

        if not isinstance(value, Mapping):
            raise RolloutConfigurationError("invalid rollout worker snapshot")
        try:
            if value.get("schema_version") != ROLLOUT_SCHEMA_VERSION:
                raise RolloutConfigurationError("unsupported rollout worker schema version")
            if value.get("policy_version") != ROLLOUT_POLICY_VERSION:
                raise RolloutConfigurationError("rollout worker policy version mismatch")
            channel = RolloutChannel.parse(str(value["channel"]), strict=True)
            unsafe = value["unsafe_allow_unstable"]
            if not isinstance(unsafe, bool):
                raise RolloutConfigurationError("invalid rollout worker unsafe override")

            def names(field: str) -> set[str]:
                raw = value[field]
                if not isinstance(raw, list) or not all(isinstance(item, str) for item in raw):
                    raise RolloutConfigurationError(f"invalid rollout worker field {field!r}")
                return set(_validate_names(set(raw), source=field, strict=True))

            snapshot = _resolve_snapshot(
                channel=channel,
                explicit_requested=names("explicit_requested"),
                explicit_disabled=names("explicit_disabled"),
                legacy_requested=names("legacy_requested"),
                legacy_disabled=names("legacy_disabled"),
                unsafe=unsafe,
            )
        except (KeyError, TypeError) as exc:
            raise RolloutConfigurationError("invalid rollout worker snapshot") from exc
        if value.get("registry_digest") != snapshot.registry_digest:
            raise RolloutConfigurationError("rollout worker registry digest mismatch")
        if value.get("snapshot_digest") != snapshot.snapshot_digest:
            raise RolloutConfigurationError("rollout worker snapshot digest mismatch")
        return snapshot

View on GitHub (pinned to 322425c43b)

Solutions

1. Make every feature-name field a JSON array of strings, e.g. ['memory', 'context'].
2. Wrap scalar shortcuts in a list before restore: value if isinstance(value, list) else [value].
3. Validate the handoff payload shape with a JSON schema at the producing side.

Example fix

# before
{"explicit_requested": "memory", ...}

# after
{"explicit_requested": ["memory"], ...}

NAME_FIELDS = ('explicit_requested', 'explicit_disabled', 'legacy_requested', 'legacy_disabled')
for field in NAME_FIELDS:
    value = payload.get(field)
    if not isinstance(value, list) or not all(isinstance(i, str) for i in value):
        raise ValueError(f'{field} must be a list of strings, got {value!r}')

def is_string_list(value: object) -> bool:
    return isinstance(value, list) and all(isinstance(i, str) for i in value)

try:
    snapshot = RolloutSnapshot.from_internal_dict(payload)
except RolloutConfigurationError as e:
    if 'invalid rollout worker field' in str(e):
        field = str(e).rsplit(' ', 1)[-1].strip("!r'")
        payload[field] = [payload[field]] if isinstance(payload.get(field), str) else payload.get(field, [])
        # prefer fixing the producer instead of repairing payloads
    raise

When it happens

Trigger: from_internal_dict() with 'explicit_requested': 'memory' (a bare string), a list containing non-strings ([1, 'memory']), or a dict/None where a list is expected.

Common situations: Compressing single-element lists to a scalar in config; JSON round-trips that change types; YAML anchors producing dicts where lists were intended.

Related errors

• invalid rollout worker unsafe override
• invalid rollout worker snapshot
• unsupported rollout worker schema version
• unknown rollout channel {value!r}
• rollout worker policy version mismatch

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/bedc8d21177dd4ef. Report an issue: GitHub.