{"record":{"id":"93f9a9cf04ae2c28","repo":"bytedance/deer-flow","slug":"checkpoint-checkpoint-id-not-found","errorCode":null,"errorMessage":"Checkpoint {checkpoint_id} not found","messagePattern":"Checkpoint (.+?) not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"warning","filePath":"backend/app/gateway/services.py","lineNumber":976,"sourceCode":"\n    read_config: dict[str, Any] = {\n        \"configurable\": {\n            \"thread_id\": thread_id,\n            \"checkpoint_ns\": checkpoint_ns,\n            \"checkpoint_id\": str(checkpoint_id),\n        }\n    }\n    if checkpoint_map is not None:\n        read_config[\"configurable\"][\"checkpoint_map\"] = checkpoint_map\n\n    checkpointer = get_checkpointer(request)\n    try:\n        checkpoint_tuple = await checkpointer.aget_tuple(read_config)\n    except Exception as exc:\n        logger.exception(\"Failed to validate checkpoint %s for thread %s\", checkpoint_id, sanitize_log_param(thread_id))\n        raise HTTPException(status_code=500, detail=\"Failed to validate checkpoint\") from exc\n    if checkpoint_tuple is None:\n        raise HTTPException(status_code=404, detail=f\"Checkpoint {checkpoint_id} not found\")\n\n    configurable = config.setdefault(\"configurable\", {})\n    if not isinstance(configurable, dict):\n        raise HTTPException(status_code=400, detail=\"request config configurable must be an object\")\n    configurable[\"thread_id\"] = thread_id\n    configurable[\"checkpoint_ns\"] = checkpoint_ns\n    configurable[\"checkpoint_id\"] = str(checkpoint_id)\n    if checkpoint_map is not None:\n        configurable[\"checkpoint_map\"] = checkpoint_map\n\n\nasync def ensure_checkpoint_history_seeded(\n    request: Request,\n    *,\n    thread_id: str,\n    assistant_id: str | None,\n) -> None:\n    \"\"\"Backfill an empty run-event feed from an existing checkpoint head.","sourceCodeStart":958,"sourceCodeEnd":994,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/services.py#L958-L994","documentation":"HTTP 404 raised when a run references a checkpoint_id that the checkpointer does not return a tuple for — the checkpoint does not exist (or no longer exists) for that thread/namespace. Validation happens before the run starts, so no work is performed.","triggerScenarios":"POSTing a run with checkpoint_id from an old conversation snapshot after checkpoints were pruned/cleared; typos in the id; referencing a checkpoint belonging to a different thread or checkpoint_ns.","commonSituations":"Checkpoint retention/TTL deleting old snapshots; client caching checkpoint ids across a thread reset; ids truncated or altered in transit.","solutions":["List the thread's checkpoints (history endpoint) and use a current checkpoint_id.","If checkpoints were pruned, drop the reference and run from the thread's latest state instead.","Verify the id is copied verbatim (full UUID/hex, no truncation)."],"exampleFix":"# before\n{\"checkpoint_id\": \"1ef4f797-8335\", \"input\": {...}}\n\n# after\n{\"checkpoint_id\": \"1ef4f797-8335-6428-8001-8a1506f3b775\", \"input\": {...}}","handlingStrategy":"validation","validationCode":"const cps = await fetch(`/api/threads/${tid}/checkpoints`).then(r => r.json());\nconst valid = cps.some(c => c.checkpoint_id === payload.checkpoint_id);\nif (!valid) delete payload.checkpoint_id; // run from latest state instead","typeGuard":null,"tryCatchPattern":"catch 404 'Checkpoint ... not found'; fall back to running without the checkpoint reference or refresh the id from history and retry.","preventionTips":["Fetch checkpoint ids from the thread's history at request time rather than caching them.","Treat 404 as an expected outcome of checkpoint retention and code a fallback path."],"tags":["runs","http-404","checkpoints"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}