bytedance/deer-flow · error · HTTPException

Failed to inspect checkpoint history

Error message

Failed to inspect checkpoint history

What it means

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.

Source

Thrown at backend/app/gateway/routers/thread_runs.py:554

            # Preserve the bounded chronological fallback for those records.
            logger.debug(
                "Could not resolve parent lineage for regenerate thread %s; falling back to history scan",
                sanitize_log_param(thread_id),
                exc_info=True,
            )
        except CheckpointLineageError as exc:
            logger.warning(
                "Rejected unsafe checkpoint lineage for regenerate thread %s",
                sanitize_log_param(thread_id),
                exc_info=True,
            )
            raise HTTPException(status_code=409, detail=_UNSAFE_REGENERATE_LINEAGE_DETAIL) from exc
    try:
        raw_checkpoints = await accessor.ahistory(base_config, limit=REGENERATE_HISTORY_RAW_SCAN_LIMIT)
        checkpoints = [item for item in raw_checkpoints if not _is_duration_only_checkpoint(item)]
    except Exception as exc:
        logger.exception("Failed to list checkpoints for regenerate thread %s", thread_id)
        raise HTTPException(status_code=500, detail="Failed to inspect checkpoint history") from exc

    previous_checkpoint, target_found = find_checkpoint_before_message_chronologically(raw_checkpoints, human_message_id)
    if target_found:
        if previous_checkpoint is None:
            raise HTTPException(
                status_code=409,
                detail=_MISSING_REGENERATE_BASE_DETAIL,
            )
        return previous_checkpoint

    if len(checkpoints) >= REGENERATE_HISTORY_SCAN_LIMIT:
        logger.warning(
            "Could not locate target user message %s in recent checkpoint history for thread %s (limit=%s)",
            human_message_id,
            thread_id,
            REGENERATE_HISTORY_SCAN_LIMIT,
        )
    raise HTTPException(

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Check Gateway logs for the logged exception ('Failed to list checkpoints for regenerate thread') to identify the backend error.
2. Verify checkpoint store connectivity and credentials in config.yaml (checkpointer section).
3. If a schema/serialization mismatch is shown, migrate or clear the affected thread's checkpoints.
4. Retry the regenerate once the checkpointer backend is healthy.

const health = await fetch('/api/health').then(r => r.status);
if (health !== 200) { backoff(); return; } // checkpointer likely down

try { await regeneratePrepare(threadId, messageId); } catch (e) { if (e.status === 500 && /inspect checkpoint history/.test(e.detail)) { await sleepBackoff(); retryOnce(); } else throw e; }

When it happens

Trigger: 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.

Common situations: DB restart or network blip during a regenerate request; LangGraph checkpoint schema upgrade without migrating stored blobs; wrong checkpoint DB credentials in config.yaml.

Related errors

• Failed to read latest checkpoint
• Failed to create thread
• Failed to create thread checkpoint
• Failed to create branch
• Failed to update thread

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