{"record":{"id":"0fec8692188e70a5","repo":"bytedance/deer-flow","slug":"could-not-safely-resolve-the-checkpoint-before-the","errorCode":null,"errorMessage":"Could not safely resolve the checkpoint before the target user message","messagePattern":"Could not safely resolve the checkpoint before the target user message","errorType":"http","errorClass":"HTTPException","httpStatus":409,"severity":"error","filePath":"backend/app/gateway/routers/thread_runs.py","lineNumber":548,"sourceCode":"                head_checkpoint,\n                human_message_id,\n                max_depth=REGENERATE_HISTORY_RAW_SCAN_LIMIT,\n            )\n        except CheckpointParentMissingError:\n            # Old checkpoints and imported histories may not have parent links.\n            # Preserve the bounded chronological fallback for those records.\n            logger.debug(\n                \"Could not resolve parent lineage for regenerate thread %s; falling back to history scan\",\n                sanitize_log_param(thread_id),\n                exc_info=True,\n            )\n        except CheckpointLineageError as exc:\n            logger.warning(\n                \"Rejected unsafe checkpoint lineage for regenerate thread %s\",\n                sanitize_log_param(thread_id),\n                exc_info=True,\n            )\n            raise HTTPException(status_code=409, detail=_UNSAFE_REGENERATE_LINEAGE_DETAIL) from exc\n    try:\n        raw_checkpoints = await accessor.ahistory(base_config, limit=REGENERATE_HISTORY_RAW_SCAN_LIMIT)\n        checkpoints = [item for item in raw_checkpoints if not _is_duration_only_checkpoint(item)]\n    except Exception as exc:\n        logger.exception(\"Failed to list checkpoints for regenerate thread %s\", thread_id)\n        raise HTTPException(status_code=500, detail=\"Failed to inspect checkpoint history\") from exc\n\n    previous_checkpoint, target_found = find_checkpoint_before_message_chronologically(raw_checkpoints, human_message_id)\n    if target_found:\n        if previous_checkpoint is None:\n            raise HTTPException(\n                status_code=409,\n                detail=_MISSING_REGENERATE_BASE_DETAIL,\n            )\n        return previous_checkpoint\n\n    if len(checkpoints) >= REGENERATE_HISTORY_SCAN_LIMIT:\n        logger.warning(","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/thread_runs.py#L530-L566","documentation":"Raised in _find_base_checkpoint_before_human (HTTP 409, detail _UNSAFE_REGENERATE_LINEAGE_DETAIL) when checkpoint parent-lineage resolution raises CheckpointLineageError. The server walks parent checkpoints to find the one preceding the target user message; if the lineage graph is inconsistent (cycles, missing parents, orphaned branches), it refuses rather than guess an unsafe base.","triggerScenarios":"Checkpoint chain where a parent id references a missing or corrupted checkpoint; concurrent writes from two Gateway instances interleaving checkpoints on one thread; a checkpointer migration that rewrote parent ids.","commonSituations":"Running multiple replicas against one checkpoint DB without coordination; DB partial writes or manual checkpoint surgery; version upgrades that changed checkpoint id encoding.","solutions":["Inspect the checkpoint store for the thread: verify each row's parent checkpoint exists (no dangling parent ids).","Ensure a single writer (one Gateway instance) owns a thread at a time; serialize runs per thread.","If lineage is unrecoverable, use the chronological history-scan path by fixing whatever made lineage resolution throw, or fall back to starting a fresh thread.","Check logs for the logged warning ('Rejected unsafe checkpoint lineage') with exc_info to see the underlying lineage error."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { await regeneratePrepare(threadId, messageId); } catch (e) { if (e.status === 409 && /safely resolve/.test(e.detail)) { reportThreadCorruption(threadId); // offer new-thread fallback } else throw e; }","preventionTips":["Single writer per thread (one Gateway instance)","Monitor checkpoint parent integrity","Back up checkpoint store before upgrades"],"tags":["checkpoint","lineage","regenerate","http-409"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}