bytedance/deer-flow · error · HTTPException

Could not safely resolve the checkpoint before the target us

Error message

Could not safely resolve the checkpoint before the target user message

What it means

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.

Source

Thrown at backend/app/gateway/routers/thread_runs.py:548

                head_checkpoint,
                human_message_id,
                max_depth=REGENERATE_HISTORY_RAW_SCAN_LIMIT,
            )
        except CheckpointParentMissingError:
            # Old checkpoints and imported histories may not have parent links.
            # Preserve the bounded chronological fallback for those records.
            logger.debug(
                "Could not resolve parent lineage for regenerate thread %s; falling back to history scan",
                sanitize_log_param(thread_id),
                exc_info=True,
            )
        except CheckpointLineageError as exc:
            logger.warning(
                "Rejected unsafe checkpoint lineage for regenerate thread %s",
                sanitize_log_param(thread_id),
                exc_info=True,
            )
            raise HTTPException(status_code=409, detail=_UNSAFE_REGENERATE_LINEAGE_DETAIL) from exc
    try:
        raw_checkpoints = await accessor.ahistory(base_config, limit=REGENERATE_HISTORY_RAW_SCAN_LIMIT)
        checkpoints = [item for item in raw_checkpoints if not _is_duration_only_checkpoint(item)]
    except Exception as exc:
        logger.exception("Failed to list checkpoints for regenerate thread %s", thread_id)
        raise HTTPException(status_code=500, detail="Failed to inspect checkpoint history") from exc

    previous_checkpoint, target_found = find_checkpoint_before_message_chronologically(raw_checkpoints, human_message_id)
    if target_found:
        if previous_checkpoint is None:
            raise HTTPException(
                status_code=409,
                detail=_MISSING_REGENERATE_BASE_DETAIL,
            )
        return previous_checkpoint

    if len(checkpoints) >= REGENERATE_HISTORY_SCAN_LIMIT:
        logger.warning(

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Inspect the checkpoint store for the thread: verify each row's parent checkpoint exists (no dangling parent ids).
2. Ensure a single writer (one Gateway instance) owns a thread at a time; serialize runs per thread.
3. 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.
4. Check logs for the logged warning ('Rejected unsafe checkpoint lineage') with exc_info to see the underlying lineage error.

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; }

When it happens

Trigger: 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.

Common situations: Running multiple replicas against one checkpoint DB without coordination; DB partial writes or manual checkpoint surgery; version upgrades that changed checkpoint id encoding.

Related errors

• Checkpoint is missing checkpoint_id
• Could not find an addressable checkpoint before the target u
• Could not locate target user message in recent checkpoint hi
• Only the latest completed user turn can be edited
• Only completed assistant text turns can be edited

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/0fec8692188e70a5. Report an issue: GitHub.