HKUDS/DeepTutor · error · GenerationFailure

invalid concept_graph payload: {exc}

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.

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)

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

• unexpected concept_graph payload type: {type(raw).__name__}
• Invalid {label} config: {details}
• Unsupported import source: {value!r}
• {exc}
• No fields to update

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