{"record":{"id":"725f3ce4aab831d1","repo":"bytedance/deer-flow","slug":"thread-requires-delta-mode-materialize-and-conver","errorCode":null,"errorMessage":"Thread requires delta mode; materialize and convert its checkpoints before using full mode.","messagePattern":"Thread requires delta mode; materialize and convert its checkpoints before using full mode\\.","errorType":"exception","errorClass":"CheckpointModeMismatchError","httpStatus":409,"severity":"error","filePath":"backend/app/gateway/services.py","lineNumber":771,"sourceCode":"\nclass _RawCheckpointReadAccessor:\n    \"\"\"Degraded full-mode read accessor for when the agent factory is down.\n\n    Full-mode checkpoints persist complete ``channel_values``, so reads do not\n    need the compiled graph. The fail-closed delta gate still applies: delta\n    checkpoints are rejected with :class:`CheckpointModeMismatchError` instead\n    of being served as partial state. Writes are unsupported — mutation paths\n    keep using the graph-backed accessor.\n    \"\"\"\n\n    def __init__(self, checkpointer: Any, mode: str) -> None:\n        self.checkpointer = checkpointer\n        self.mode = mode\n\n    @staticmethod\n    def _gate(tup: Any) -> None:\n        if checkpoint_tuple_uses_delta(tup):\n            raise CheckpointModeMismatchError(\"Thread requires delta mode; materialize and convert its checkpoints before using full mode.\")\n\n    async def aget(self, config: dict[str, Any]) -> _RawCheckpointSnapshot:\n        tup = await self.checkpointer.aget_tuple(config)\n        self._gate(tup)\n        return _RawCheckpointSnapshot(config, tup)\n\n    async def ahistory(self, config: dict[str, Any], *, limit: int | None = None) -> list[_RawCheckpointSnapshot]:\n        if limit is not None and limit <= 0:\n            return []\n        result: list[_RawCheckpointSnapshot] = []\n        before = None\n        walk_config = config\n        if config.get(\"configurable\", {}).get(\"checkpoint_id\"):\n            # Pregel's get_state_history treats config.checkpoint_id as the\n            # inclusive start of the walk, while alist(before=...) is\n            # exclusive — fetch the anchor explicitly so the degraded path\n            # matches the graph path.\n            before = config","sourceCodeStart":753,"sourceCodeEnd":789,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/services.py#L753-L789","documentation":"CheckpointModeMismatchError raised by the delta-gating checkpointer wrapper: the thread's checkpoints use the delta (incremental) format, but the accessor was constructed in full mode. Full-mode reads would silently serve partial state, so any aget/ahistory touching a delta checkpoint raises instead. Writes are not supported on this wrapper; mutation paths use the graph-backed accessor.","triggerScenarios":"Reading state/history of a thread created or written by a DeerFlow version that stores delta checkpoints, through a code path that requests full-mode snapshots (e.g. a state or history endpoint configured for full mode).","commonSituations":"Upgrading/migrating between DeerFlow versions where the checkpoint format changed to delta; mixed-version deployments where one gateway writes deltas and another reads in full mode; running a migration halfway.","solutions":["Materialize and convert the thread's checkpoints from delta to full format using DeerFlow's checkpoint conversion/migration tooling, then retry.","Serve reads for that thread through delta mode (the accessor mode that matches how it was written).","Avoid mixed versions writing/reading the same thread store; upgrade all gateway replicas together."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch CheckpointModeMismatchError; fall back to delta-mode reads for that thread, and schedule checkpoint conversion before retrying full mode.","preventionTips":["Run DeerFlow's checkpoint conversion/migration whenever upgrading across the format change; don't stop halfway.","Never run mixed gateway versions against one thread store.","Gate full-mode state reads behind a post-migration check."],"tags":["checkpoints","state","migration","version-drift"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}