{"record":{"id":"cddd7391d77af09a","repo":"bytedance/deer-flow","slug":"failed-to-inspect-checkpoint-history","errorCode":null,"errorMessage":"Failed to inspect checkpoint history","messagePattern":"Failed to inspect checkpoint history","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"backend/app/gateway/routers/thread_runs.py","lineNumber":554,"sourceCode":"            # Preserve the bounded chronological fallback for those records.\n            logger.debug(\n                \"Could not resolve parent lineage for regenerate thread %s; falling back to history scan\",\n                sanitize_log_param(thread_id),\n                exc_info=True,\n            )\n        except CheckpointLineageError as exc:\n            logger.warning(\n                \"Rejected unsafe checkpoint lineage for regenerate thread %s\",\n                sanitize_log_param(thread_id),\n                exc_info=True,\n            )\n            raise HTTPException(status_code=409, detail=_UNSAFE_REGENERATE_LINEAGE_DETAIL) from exc\n    try:\n        raw_checkpoints = await accessor.ahistory(base_config, limit=REGENERATE_HISTORY_RAW_SCAN_LIMIT)\n        checkpoints = [item for item in raw_checkpoints if not _is_duration_only_checkpoint(item)]\n    except Exception as exc:\n        logger.exception(\"Failed to list checkpoints for regenerate thread %s\", thread_id)\n        raise HTTPException(status_code=500, detail=\"Failed to inspect checkpoint history\") from exc\n\n    previous_checkpoint, target_found = find_checkpoint_before_message_chronologically(raw_checkpoints, human_message_id)\n    if target_found:\n        if previous_checkpoint is None:\n            raise HTTPException(\n                status_code=409,\n                detail=_MISSING_REGENERATE_BASE_DETAIL,\n            )\n        return previous_checkpoint\n\n    if len(checkpoints) >= REGENERATE_HISTORY_SCAN_LIMIT:\n        logger.warning(\n            \"Could not locate target user message %s in recent checkpoint history for thread %s (limit=%s)\",\n            human_message_id,\n            thread_id,\n            REGENERATE_HISTORY_SCAN_LIMIT,\n        )\n    raise HTTPException(","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/thread_runs.py#L536-L572","documentation":"Raised in _find_base_checkpoint_before_human (HTTP 500) when accessor.ahistory() throws while listing checkpoint history for the regenerate base lookup. This is a server-side infrastructure failure of the checkpointer (DB down, deserialization error), not a client-input problem.","triggerScenarios":"Checkpoint database connection dropped or timed out; checkpoint blob deserialization failure (schema changed between writer and reader); checkpointer backend (Postgres/Redis/SQLite) unavailable or misconfigured.","commonSituations":"DB restart or network blip during a regenerate request; LangGraph checkpoint schema upgrade without migrating stored blobs; wrong checkpoint DB credentials in config.yaml.","solutions":["Check Gateway logs for the logged exception ('Failed to list checkpoints for regenerate thread') to identify the backend error.","Verify checkpoint store connectivity and credentials in config.yaml (checkpointer section).","If a schema/serialization mismatch is shown, migrate or clear the affected thread's checkpoints.","Retry the regenerate once the checkpointer backend is healthy."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"const health = await fetch('/api/health').then(r => r.status);\nif (health !== 200) { backoff(); return; } // checkpointer likely down","typeGuard":null,"tryCatchPattern":"try { await regeneratePrepare(threadId, messageId); } catch (e) { if (e.status === 500 && /inspect checkpoint history/.test(e.detail)) { await sleepBackoff(); retryOnce(); } else throw e; }","preventionTips":["Health-check the Gateway before regenerate calls","Keep checkpoint DB highly available","Alert on 500s from checkpoint endpoints"],"tags":["checkpoint","database","http-500","infrastructure"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}