bytedance/deer-flow · error · HTTPException

Failed to inspect checkpoint history

Error message

Failed to inspect checkpoint history

What it means

Error "Failed to inspect checkpoint history" thrown in bytedance/deer-flow.

Source

Thrown at backend/app/gateway/routers/threads.py:281

        )
    except CheckpointLineageError as exc:
        thread_id = config.get("configurable", {}).get("thread_id", "")
        logger.warning(
            "Rejected unsafe checkpoint lineage for branch thread %s",
            sanitize_log_param(thread_id),
            exc_info=True,
        )
        raise HTTPException(status_code=409, detail="This turn can no longer be branched from.") from exc

    try:
        history = await accessor.ahistory(config, limit=_BRANCH_HISTORY_RAW_SCAN_LIMIT)
    except _CHECKPOINT_MODE_ERRORS as exc:
        thread_id = config.get("configurable", {}).get("thread_id", "")
        raise _checkpoint_mode_http_error(exc, thread_id) from exc
    except Exception as exc:
        thread_id = config.get("configurable", {}).get("thread_id", "")
        logger.exception("Failed to scan replay checkpoint history for thread %s", sanitize_log_param(thread_id))
        raise HTTPException(status_code=500, detail="Failed to inspect checkpoint history") from exc

    replay_base, target_found = find_checkpoint_before_message_chronologically(history, target_human_id)
    if not target_found:
        logger.warning(
            "Could not locate branch user message %s in chronological history for thread %s",
            sanitize_log_param(target_human_id),
            sanitize_log_param(config.get("configurable", {}).get("thread_id", "")),
        )
    return replay_base


def _ignore_branch_user_data(directory: str, names: list[str]) -> set[str]:
    ignored: set[str] = set()
    base = Path(directory)
    for name in names:
        path = base / name
        if name.startswith(".upload-") and name.endswith(".part"):
            ignored.add(name)

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Check checkpoint storage health (database backend connectivity) and retry.
2. See Gateway logs for the underlying checkpoint store error.

When it happens

Trigger: Thrown at backend/app/gateway/routers/threads.py:281 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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