bytedance/deer-flow · error · HTTPException

Failed to create branch

Error message

Failed to create branch

What it means

500 from branch_thread when writing the forked checkpoint(s) to the new thread fails: the branch_accessor.aupdate / aput sequence that copies snapshot values onto the branch raises an unexpected exception (checkpoint-mode errors are mapped separately to _checkpoint_mode_http_error). The traceback is logged with the new thread id.

Source

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

    try:
        head_config = new_config
        if replay_base_tuple is not None:
            head_config = await branch_accessor.aupdate(
                new_config,
                branch_values(replay_base_tuple),
                as_node="branch",
            )
            head_config.setdefault("metadata", {}).update(checkpoint_metadata_updates)
        await branch_accessor.aupdate(
            head_config,
            branch_values(snapshot),
            as_node="branch",
        )
    except _CHECKPOINT_MODE_ERRORS as exc:
        raise _checkpoint_mode_http_error(exc, new_thread_id) from exc
    except Exception:
        logger.exception("Failed to write branch checkpoint for thread %s", sanitize_log_param(new_thread_id))
        raise HTTPException(status_code=500, detail="Failed to create branch") from None

    try:
        await thread_store.create(
            new_thread_id,
            assistant_id=source_record.get("assistant_id"),
            display_name=display_name,
            metadata=branch_metadata,
            **thread_owner_kwargs,
        )
    except Exception:
        logger.exception("Failed to write branch thread_meta for %s", sanitize_log_param(new_thread_id))
        raise HTTPException(status_code=500, detail="Failed to create branch") from None

    # The thread feed (GET /messages, /messages/page) reads the run-event
    # store, not checkpoints, and a fresh branch has no run_events — so the
    # inherited history would vanish from the UI as soon as the branch's
    # first run refreshes the feed (#4380 problem 2). Seed the branch's
    # run_events from the same checkpoint snapshot the branch was created

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Read the 'Failed to write branch checkpoint for thread %s' log for the root cause.
2. Verify checkpointer DB health and schema (checkpoint tables present, serializer versions aligned).
3. Retry the branch once storage is healthy; branch creation is read-only on the source thread so retry is safe.
4. If state is too large to serialize, reduce thread state size or fix the serializer before branching.

try { await api.post(`/api/threads/${id}/branches`, body); }
catch (err) {
  if (err.status === 500) { await waitForCheckpointStoreHealth(); retryOnce(); } // source thread is untouched by a failed branch
  else throw err;
}

When it happens

Trigger: POST /threads/{id}/branches while checkpoint storage errors mid-copy: DB down, serialization failure of branch_values(snapshot), lock timeout, or checkpoint schema mismatch.

Common situations: Checkpointer database unavailable or migrated incompletely; large snapshot state failing blob serialization; concurrent runs holding write locks on the checkpoints table.

Related errors

• Failed to create thread checkpoint
• Failed to get thread
• Failed to create thread
• Failed to update thread
• Failed to read thread goal

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