{"record":{"id":"deff033944b3389d","repo":"bytedance/deer-flow","slug":"failed-to-create-branch","errorCode":null,"errorMessage":"Failed to create branch","messagePattern":"Failed to create branch","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"backend/app/gateway/routers/threads.py","lineNumber":901,"sourceCode":"    try:\n        head_config = new_config\n        if replay_base_tuple is not None:\n            head_config = await branch_accessor.aupdate(\n                new_config,\n                branch_values(replay_base_tuple),\n                as_node=\"branch\",\n            )\n            head_config.setdefault(\"metadata\", {}).update(checkpoint_metadata_updates)\n        await branch_accessor.aupdate(\n            head_config,\n            branch_values(snapshot),\n            as_node=\"branch\",\n        )\n    except _CHECKPOINT_MODE_ERRORS as exc:\n        raise _checkpoint_mode_http_error(exc, new_thread_id) from exc\n    except Exception:\n        logger.exception(\"Failed to write branch checkpoint for thread %s\", sanitize_log_param(new_thread_id))\n        raise HTTPException(status_code=500, detail=\"Failed to create branch\") from None\n\n    try:\n        await thread_store.create(\n            new_thread_id,\n            assistant_id=source_record.get(\"assistant_id\"),\n            display_name=display_name,\n            metadata=branch_metadata,\n            **thread_owner_kwargs,\n        )\n    except Exception:\n        logger.exception(\"Failed to write branch thread_meta for %s\", sanitize_log_param(new_thread_id))\n        raise HTTPException(status_code=500, detail=\"Failed to create branch\") from None\n\n    # The thread feed (GET /messages, /messages/page) reads the run-event\n    # store, not checkpoints, and a fresh branch has no run_events — so the\n    # inherited history would vanish from the UI as soon as the branch's\n    # first run refreshes the feed (#4380 problem 2). Seed the branch's\n    # run_events from the same checkpoint snapshot the branch was created","sourceCodeStart":883,"sourceCodeEnd":919,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/threads.py#L883-L919","documentation":"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.","triggerScenarios":"POST /threads/{id}/branches while checkpoint storage errors mid-copy: DB down, serialization failure of branch_values(snapshot), lock timeout, or checkpoint schema mismatch.","commonSituations":"Checkpointer database unavailable or migrated incompletely; large snapshot state failing blob serialization; concurrent runs holding write locks on the checkpoints table.","solutions":["Read the 'Failed to write branch checkpoint for thread %s' log for the root cause.","Verify checkpointer DB health and schema (checkpoint tables present, serializer versions aligned).","Retry the branch once storage is healthy; branch creation is read-only on the source thread so retry is safe.","If state is too large to serialize, reduce thread state size or fix the serializer before branching."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { await api.post(`/api/threads/${id}/branches`, body); }\ncatch (err) {\n  if (err.status === 500) { await waitForCheckpointStoreHealth(); retryOnce(); } // source thread is untouched by a failed branch\n  else throw err;\n}","preventionTips":["Branch when the thread is idle and checkpoint storage is healthy.","Keep thread state size bounded so branch_values(snapshot) serializes cleanly.","Treat branch failure as safe to retry — the source thread is never mutated."],"tags":["threads","branching","checkpointer","http-500","database"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}