bytedance/deer-flow · error · HTTPException

Unknown thread-state field(s): {', '.join(unknown_fields)}

Error message

Unknown thread-state field(s): {', '.join(unknown_fields)}

What it means

Error "Unknown thread-state field(s): {', '.join(unknown_fields)}" thrown in bytedance/deer-flow.

Source

Thrown at backend/app/gateway/routers/threads.py:1273

            raise HTTPException(status_code=500, detail="Failed to get thread state")
        if checkpoint_tuple is None:
            raise HTTPException(status_code=404, detail=f"Checkpoint {body.checkpoint_id} not found")

    mutation_node = body.as_node or "manual_state_update"
    # Resolve through the shared boundary (thread metadata -> assistant_id ->
    # effective schema) so extension middleware channels stay writable.
    accessor, read_config = await build_thread_checkpoint_state_mutation_accessor(
        request,
        thread_id=thread_id,
        as_node=mutation_node,
        checkpoint_id=body.checkpoint_id,
    )
    values = dict(body.values or {})
    writable_channels = graph_writable_channels(getattr(accessor, "graph", None))
    if writable_channels is not None:
        unknown_fields = sorted(set(values) - writable_channels)
        if unknown_fields:
            raise HTTPException(
                status_code=422,
                detail=f"Unknown thread-state field(s): {', '.join(unknown_fields)}",
            )
    reducer_fields = graph_reducer_channels(getattr(accessor, "graph", None))
    if reducer_fields is None:
        reducer_fields = THREAD_STATE_REDUCER_FIELDS
    updates = {key: Overwrite(value) if key in reducer_fields else value for key, value in values.items()}
    try:
        async with reserve_checkpoint_write(request, thread_id, user_id=get_effective_user_id()):
            updated_config = await accessor.aupdate(
                read_config,
                updates,
                as_node=mutation_node,
            )
            snapshot = await accessor.aget(updated_config)
    except ConflictError:
        raise HTTPException(status_code=409, detail="Thread has a run in flight. Update state after the run finishes.") from None
    except _CHECKPOINT_MODE_ERRORS as exc:

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Remove the unknown fields listed in the error from the state update payload.
2. Check the thread-state API schema for the allowed field names.

When it happens

Trigger: Thrown at backend/app/gateway/routers/threads.py:1273 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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