deer-flow/backend/app/gateway/checkpoint_mode_errors.py
哈基米 f95d4f6353
fix(gateway): map checkpoint-mode errors in run-prepare routes (#8296)
* fix(gateway): map checkpoint-mode errors in run-prepare routes

The regenerate and edit-regenerate prepare routes read the same thread
checkpoints as the threads router but built the accessor and read the
latest checkpoint under a generic handler, so a delta/full mismatch
surfaced as a 500 instead of the 409 that names the mode flip. Move the
mapper to a shared module, reuse it for the accessor, latest-checkpoint
and history-scan failures, and update the troubleshooting page now that
the routes behave like the other state surfaces.

* fix(gateway): preserve route-level HTTP errors in run-prepare

The checkpoint-read fallback now sits around the accessor build, so a
config-loading HTTPException from the accessor was being rewritten as a
generic 500. Re-raise HTTPException before the generic handler and cover
the 503 passthrough with a test.

* docs: confirm the mode mismatch before advising a restart

A null token usage or a /runs/wait error body can also come from a
configuration or token-counting failure, so the troubleshooting entry
should point at the 409 from the thread/state endpoints first.

* fix(gateway): remove duplicate checkpoint imports after merge

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
2026-11-17 12:10:08 +08:00

24 lines
1018 B
Python

"""Map checkpoint-mode guard failures to precise HTTP statuses.
A mismatch means the thread's persisted checkpoints conflict with the process's
frozen mode (operator-actionable, 409); a reconfiguration means the process
itself is mid mode-flip (transient, 503). Both must surface their message — a
generic 500 would force operators to grep logs to discover the root cause after
a mode flip.
"""
from __future__ import annotations
from fastapi import HTTPException
from deerflow.runtime.checkpoint_mode import CheckpointModeMismatchError, CheckpointModeReconfigurationError
CHECKPOINT_MODE_ERRORS = (CheckpointModeMismatchError, CheckpointModeReconfigurationError)
def checkpoint_mode_http_error(exc: Exception, thread_id: str) -> HTTPException:
"""Return the HTTP error for a checkpoint-mode guard failure."""
if isinstance(exc, CheckpointModeMismatchError):
return HTTPException(status_code=409, detail=f"Thread {thread_id}: {exc}")
return HTTPException(status_code=503, detail=str(exc))