ScrapeGraphAI/Scrapegraph-ai · error · InvalidStateError

comparison_result missing 'explanation' key

Error message

comparison_result missing 'explanation' key

What it means

semantic_focused_analysis requires comparison_result to contain an 'explanation' key; raised immediately after the 'differences' check when it is missing. Together the two checks define the required shape of comparison_result.

Source

Thrown at scrapegraphai/utils/code_error_analysis.py:314

        }
        >>> comparison_result = {
            'differences': ['Missing docstring', 'No type hints'],
            'explanation': 'The code is missing documentation'
        }
        >>> analysis = semantic_focused_analysis(state, comparison_result, mock_llm)
    """
    try:
        # Validate state using Pydantic model
        validated_state = CodeAnalysisState(
            generated_code=state.get("generated_code", ""),
            errors=state.get("errors", {}),
        )

        # Validate comparison_result
        if "differences" not in comparison_result:
            raise InvalidStateError("comparison_result missing 'differences' key")
        if "explanation" not in comparison_result:
            raise InvalidStateError("comparison_result missing 'explanation' key")

        # Create prompt template and chain
        prompt = PromptTemplate(
            template=get_optimal_analysis_template("semantic"),
            input_variables=["generated_code", "differences", "explanation"],
        )
        chain = prompt | llm_model | StrOutputParser()

        # Execute chain with validated inputs
        return chain.invoke(
            {
                "generated_code": validated_state.generated_code,
                "differences": json.dumps(comparison_result["differences"], indent=2),
                "explanation": comparison_result["explanation"],
            }
        )

    except KeyError as e:

View on GitHub (pinned to 532dfffbf6)

Solutions

1. Normalize comparison_result to include a non-empty 'explanation' (default to '' if absent)
2. Fix/parse the upstream comparison step so both keys are always produced
3. Add a unit test asserting the comparison output shape

Example fix

# before
semantic_focused_analysis(state, {"differences": diffs}, llm)
# after
semantic_focused_analysis(state, {"differences": diffs, "explanation": expl or "no explanation"}, llm)

comparison_result.setdefault("explanation", "")
assert "explanation" in comparison_result

def has_explanation(cr) -> bool:
    return isinstance(cr, dict) and isinstance(cr.get("explanation"), str)

from scrapegraphai.utils.code_error_analysis import InvalidStateError
try:
    semantic_focused_analysis(state, comparison_result, llm_model)
except InvalidStateError as e:
    if "explanation" in str(e):
        comparison_result["explanation"] = ""
        # safe to retry once

When it happens

Trigger: Calling semantic_comparison_loop / semantic_focused_analysis with a comparison_result dict that has 'differences' but no 'explanation' — typical when the upstream comparison LLM omitted explanation or output parsing kept only part of the response.

Common situations: Comparison step's LLM returned malformed/partial JSON; custom comparison implementation that never produces 'explanation'; schema drift between scrapegraphai versions.

Related errors

• comparison_result missing 'differences' key
• Missing required key: {e}
• LLM configuration must include an 'api_key'.
• langchain_google_genai is not installed. Please install it u
• No audio generated from the text.

AI-assisted analysis of ScrapeGraphAI/Scrapegraph-ai@532dfffbf6 (2026-08-28). Data as JSON: /api/errors/08699f012c4e91a4. Report an issue: GitHub.