{"record":{"id":"f5f594fc81403a8c","repo":"headroomlabs-ai/headroom","slug":"rollout-worker-policy-version-mismatch","errorCode":null,"errorMessage":"rollout worker policy version mismatch","messagePattern":"rollout worker policy version mismatch","errorType":"exception","errorClass":"RolloutConfigurationError","httpStatus":null,"severity":"error","filePath":"headroom/rollout.py","lineNumber":294,"sourceCode":"            \"channel\": self.channel.value,\n            \"unsafe_allow_unstable\": self.unsafe_allow_unstable,\n            \"explicit_requested\": sorted(self.config.explicit_requested),\n            \"explicit_disabled\": sorted(self.config.explicit_disabled),\n            \"legacy_requested\": sorted(self.config.legacy_requested),\n            \"legacy_disabled\": sorted(self.config.legacy_disabled),\n        }\n\n    @classmethod\n    def from_internal_dict(cls, value: Mapping[str, object]) -> RolloutSnapshot:\n        \"\"\"Validate and restore a snapshot serialized for worker handoff.\"\"\"\n\n        if not isinstance(value, Mapping):\n            raise RolloutConfigurationError(\"invalid rollout worker snapshot\")\n        try:\n            if value.get(\"schema_version\") != ROLLOUT_SCHEMA_VERSION:\n                raise RolloutConfigurationError(\"unsupported rollout worker schema version\")\n            if value.get(\"policy_version\") != ROLLOUT_POLICY_VERSION:\n                raise RolloutConfigurationError(\"rollout worker policy version mismatch\")\n            channel = RolloutChannel.parse(str(value[\"channel\"]), strict=True)\n            unsafe = value[\"unsafe_allow_unstable\"]\n            if not isinstance(unsafe, bool):\n                raise RolloutConfigurationError(\"invalid rollout worker unsafe override\")\n\n            def names(field: str) -> set[str]:\n                raw = value[field]\n                if not isinstance(raw, list) or not all(isinstance(item, str) for item in raw):\n                    raise RolloutConfigurationError(f\"invalid rollout worker field {field!r}\")\n                return set(_validate_names(set(raw), source=field, strict=True))\n\n            snapshot = _resolve_snapshot(\n                channel=channel,\n                explicit_requested=names(\"explicit_requested\"),\n                explicit_disabled=names(\"explicit_disabled\"),\n                legacy_requested=names(\"legacy_requested\"),\n                legacy_disabled=names(\"legacy_disabled\"),\n                unsafe=unsafe,","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/rollout.py#L276-L312","documentation":"Raised by RolloutSnapshot.from_internal_dict() when the restored dict's 'policy_version' does not equal ROLLOUT_POLICY_VERSION. Independent of the wire schema version, this pins the rollout policy semantics (how channels/features resolve), so snapshots cross a policy change must be rebuilt rather than reinterpreted.","triggerScenarios":"Restoring a snapshot produced under an older rollout policy — typically after upgrading headroom past a policy revision — or mutating the 'policy_version' field in a hand-built dict.","commonSituations":"Version skew between the process that serialized the snapshot and the one restoring it (rolling deploy, canary worker); cached/persisted snapshots surviving an upgrade; copy-pasted snapshot fixtures in tests.","solutions":["Upgrade all processes to the same headroom version so ROLLOUT_POLICY_VERSION matches.","Regenerate the snapshot at the current process and re-handoff instead of restoring the stale one.","Treat policy-version mismatch as a signal to rebuild from config, not to patch the dict."],"exampleFix":"# before\nsnapshot = RolloutSnapshot.from_internal_dict(stale_dict)\n\n# after\n# re-serialize from the current process after upgrading both sides\nsnapshot = RolloutSnapshot.from_internal_dict(current.to_internal_dict())","handlingStrategy":"validation","validationCode":"from headroom.rollout import ROLLOUT_POLICY_VERSION\n\nif payload.get('policy_version') != ROLLOUT_POLICY_VERSION:\n    raise HandoffVersionError('policy version skew between producer and consumer')","typeGuard":"def snapshot_policy_matches(payload: Mapping) -> bool:\n    from headroom.rollout import ROLLOUT_POLICY_VERSION\n    return payload.get('policy_version') == ROLLOUT_POLICY_VERSION","tryCatchPattern":"try:\n    snapshot = RolloutSnapshot.from_internal_dict(payload)\nexcept RolloutConfigurationError as e:\n    if 'policy version' in str(e):\n        snapshot = resolve_fresh_snapshot()  # rebuild under current policy\n    else:\n        raise","preventionTips":["Treat policy-version mismatch as a rebuild signal, never patch the field in the dict.","Coordinate headroom upgrades so all snapshot producers/consumers move together.","Monitor for this error during canary deploys as a version-skew detector."],"tags":["versioning","rollout","policy","worker-handoff"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}