HKUDS/DeepTutor · error · GenerationFailure

invalid concept_graph payload

Error message

invalid concept_graph payload: {exc}

What it means

A `concept_graph` payload WAS supplied as a dict, but `ConceptGraph.model_validate(raw)` rejected it — schema validation failed (missing required fields, wrong types, bad edge/node shapes). The Pydantic error text is chained into the message.

Solutions

1. Read the chained validation error to see the exact failing field
2. Construct payloads via the ConceptGraph model itself (model_validate on your validated dict, or build with the class) so type errors surface early
3. Add a Pydantic validation step at your pipeline boundary before handing data to the block
4. Pin/align versions so schema fields match what your producer emits

Example fix

# before
ctx.extra["concept_graph"] = {"nodes": "n1", "edges": []}

# after
from deeptutor... import ConceptGraph
graph = ConceptGraph.model_validate({"nodes": [...], "edges": [...]})
ctx.extra["concept_graph"] = graph

from pydantic import ValidationError
try:
    ConceptGraph.model_validate(payload)
except ValidationError as e:
    fix_or_reject(payload, e.errors())

def is_valid_graph_payload(raw) -> bool:
    if isinstance(raw, ConceptGraph):
        return True
    if isinstance(raw, dict):
        try:
            ConceptGraph.model_validate(raw)
            return True
        except Exception:
            return False
    return False

from deeptutor.book.compiler import GenerationFailure
try:
    await cg_gen._generate(ctx)
except GenerationFailure as e:
    if "invalid concept_graph payload" in str(e):
        ctx.extra["concept_graph"] = ConceptGraph.model_validate(sanitized(raw))
        return await cg_gen._generate(ctx)
    raise

When it happens

Trigger: Passing a hand-built or externally serialized dict in `extra['concept_graph']` / block params that doesn't satisfy the ConceptGraph schema — missing node ids, edges referencing unknown nodes, wrong field types, JSON round-tripped through a lossy step.

Common situations: Feeding LLM-generated or user-edited graph JSON; version skew where ConceptGraph gained required fields; pipelines that build dicts ad hoc instead of using the model.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid config
• unexpected concept_graph payload type
• concept_graph payload missing from BlockContext.extra
• {exc}
• graphrag_model_incompatible

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/7ce490942340529e. Report an issue: GitHub.

Appendix: source

Thrown at deeptutor/book/blocks/concept_graph.py:98

    return "\n".join(lines)


class ConceptGraphGenerator(BlockGenerator):
    block_type = BlockType.CONCEPT_GRAPH

    async def _generate(
        self, ctx: BlockContext
    ) -> tuple[dict[str, Any], list[SourceAnchor], dict[str, Any]]:
        raw = ctx.extra.get("concept_graph") or ctx.block.params.get("concept_graph")
        if raw is None:
            raise GenerationFailure("concept_graph payload missing from BlockContext.extra")
        if isinstance(raw, ConceptGraph):
            graph = raw
        elif isinstance(raw, dict):
            try:
                graph = ConceptGraph.model_validate(raw)
            except Exception as exc:
                raise GenerationFailure(f"invalid concept_graph payload: {exc}") from exc
        else:
            raise GenerationFailure(f"unexpected concept_graph payload type: {type(raw).__name__}")

        chapters_index = ctx.extra.get("chapter_index") or []
        if not isinstance(chapters_index, list):
            chapters_index = []

        mermaid_src = render_mermaid(graph)

        # Build a node→chapter lookup for the interactive sidebar.
        node_to_chapter: dict[str, str] = {}
        for n in graph.nodes:
            if n.chapter_id:
                node_to_chapter[n.id] = n.chapter_id

        return (
            {
                "render_type": "concept_graph",

View on GitHub (pinned to 3e82f13042)