bytedance/deer-flow · error · HTTPException

Checkpoint {body.checkpoint_id} not found

Error message

Checkpoint {body.checkpoint_id} not found

What it means

Error "Checkpoint {body.checkpoint_id} not found" thrown in bytedance/deer-flow.

Source

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

    thread_store = get_thread_store(request)
    if body.checkpoint_id is not None:
        if not body.checkpoint_id:
            raise HTTPException(status_code=404, detail="Checkpoint not found")
        selected_config = {
            "configurable": {
                "thread_id": thread_id,
                "checkpoint_ns": "",
                "checkpoint_id": body.checkpoint_id,
            }
        }
        try:
            checkpoint_tuple = await get_checkpointer(request).aget_tuple(selected_config)
        except Exception:
            logger.exception("Failed to get state for thread %s", sanitize_log_param(thread_id))
            raise HTTPException(status_code=500, detail="Failed to get thread state")
        if checkpoint_tuple is None:
            raise HTTPException(status_code=404, detail=f"Checkpoint {body.checkpoint_id} not found")

    mutation_node = body.as_node or "manual_state_update"
    # Resolve through the shared boundary (thread metadata -> assistant_id ->
    # effective schema) so extension middleware channels stay writable.
    accessor, read_config = await build_thread_checkpoint_state_mutation_accessor(
        request,
        thread_id=thread_id,
        as_node=mutation_node,
        checkpoint_id=body.checkpoint_id,
    )
    values = dict(body.values or {})
    writable_channels = graph_writable_channels(getattr(accessor, "graph", None))
    if writable_channels is not None:
        unknown_fields = sorted(set(values) - writable_channels)
        if unknown_fields:
            raise HTTPException(
                status_code=422,
                detail=f"Unknown thread-state field(s): {', '.join(unknown_fields)}",

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Use a checkpoint_id from the thread's current checkpoint history.
2. The checkpoint may have been garbage-collected; pick a newer one.

When it happens

Trigger: Thrown at backend/app/gateway/routers/threads.py:1257 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/436b4b67b789b207. Report an issue: GitHub.