{"record":{"id":"f4bb72c551ef2529","repo":"bytedance/deer-flow","slug":"failed-to-create-thread-checkpoint","errorCode":null,"errorMessage":"Failed to create thread checkpoint","messagePattern":"Failed to create thread checkpoint","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"backend/app/gateway/routers/threads.py","lineNumber":612,"sourceCode":"    record = await thread_store.get(thread_id, **thread_owner_kwargs)\n    if record is None and thread_owner_user_id:\n        unscoped_record = await thread_store.get(thread_id, user_id=None)\n        if unscoped_record is not None:\n            if unscoped_record.get(\"user_id\") != thread_owner_user_id:\n                await thread_store.update_owner(thread_id, thread_owner_user_id, user_id=None)\n            record = await thread_store.get(thread_id, **thread_owner_kwargs)\n    if record is None:\n        try:\n            await thread_store.create(thread_id, metadata={}, **thread_owner_kwargs)\n        except Exception:\n            logger.exception(\"Failed to create thread_meta for goal thread %s\", sanitize_log_param(thread_id))\n            raise HTTPException(status_code=500, detail=\"Failed to create thread\") from None\n\n    try:\n        await ensure_thread_checkpoint(checkpointer, thread_id)\n    except Exception:\n        logger.exception(\"Failed to create goal checkpoint for thread %s\", sanitize_log_param(thread_id))\n        raise HTTPException(status_code=500, detail=\"Failed to create thread checkpoint\") from None\n\n\n# ---------------------------------------------------------------------------\n# Endpoints\n# ---------------------------------------------------------------------------\n\n\n@router.delete(\"/{thread_id}\", response_model=ThreadDeleteResponse)\n@require_permission(\"threads\", \"delete\", owner_check=True, require_existing=True)\nasync def delete_thread_data(thread_id: str, request: Request) -> ThreadDeleteResponse:\n    \"\"\"Delete local persisted filesystem data for a thread.\n\n    Cleans DeerFlow-managed thread directories, removes checkpoint data,\n    and removes the thread_meta row from the configured ThreadMetaStore\n    (sqlite or memory).\n    \"\"\"\n    from app.gateway.deps import get_thread_store\n","sourceCodeStart":594,"sourceCodeEnd":630,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/threads.py#L594-L630","documentation":"Raised when ensure_thread_checkpoint(checkpointer, thread_id) fails while provisioning a checkpoint for the goal flow. The checkpointer (LangGraph SQL checkpointer) must write an initial checkpoint row; any exception from that write is logged with the thread id and returned as a 500 'Failed to create thread checkpoint'.","triggerScenarios":"PUT /api/threads/{thread_id}/goal on a fresh thread when checkpoint storage is unavailable (DB down, checkpoint tables missing, serializer errors on initial state), or the checkpoint writer hits a constraint/serialization failure.","commonSituations":"Checkpointer database not migrated to the LangGraph checkpoint schema after an upgrade; SQLite file locked by a concurrent writer; connection pool exhausted under load; Postgres auth/permissions changed.","solutions":["Check the Gateway log for 'Failed to create goal checkpoint for thread %s' — the chained exception names the driver error.","Run the backend migration step so checkpoints/checkpoint_writes/checkpoint_blobs tables exist and match the installed langgraph-checkpoint version.","Verify checkpointer config in config.yaml (URL, pool size) and database health.","Retry the PUT after the storage issue is fixed; the flow is idempotent for existing checkpoints."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { await api.put(`/threads/${id}/goal`, body); }\ncatch (err) {\n  if (err.status === 500 && /checkpoint/i.test(err.detail)) { await waitForDbHealth(); retry(); }\n  else throw err;\n}","preventionTips":["Run the checkpoint-table migrations whenever langgraph-checkpoint is upgraded.","Gate goal-setting UI on Gateway/db health checks.","Keep the checkpointer connection pool sized for concurrent runs."],"tags":["threads","checkpointer","database","goals","http-500"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}