bytedance/deer-flow · error · HTTPException

Checkpoint not found

Error message

Checkpoint not found

What it means

Error "Checkpoint not found" thrown in bytedance/deer-flow.

Source

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

        metadata=metadata,
        checkpoint={"id": checkpoint_id, "ts": coerce_iso(created_at)},
        checkpoint_id=checkpoint_id,
        parent_checkpoint_id=parent_checkpoint_id,
        created_at=coerce_iso(created_at),
        tasks=tasks,
    )


@router.post("/{thread_id}/state", response_model=ThreadStateResponse)
@require_permission("threads", "write", owner_check=True, require_existing=True)
async def update_thread_state(thread_id: ThreadId, body: ThreadStateUpdateRequest, request: Request) -> ThreadStateResponse:
    """Replace selected thread-state fields through the materialized graph."""
    from app.gateway.deps import get_thread_store

    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.

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Refresh the thread state; the checkpoint may have been pruned.
2. List checkpoints for the thread and use an existing checkpoint_id.

When it happens

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