HKUDS/DeepTutor · error · GenerationFailure

figure generation failed: {exc}

Error message

figure generation failed: {exc}

What it means

The figure block wraps the whole FigureGenerator pipeline (analysis → code generation → validation/review) in a try/except; any exception escaping it — LLM API errors, parsing errors, internal assertion failures — is re-raised as GenerationFailure('figure generation failed: ...'). The original exception is chained and logged with a warning traceback.

Source

Thrown at deeptutor/book/blocks/figure.py:107

                analysis=analysis,
            )
            ok, validation_error = validate_visualization(code, analysis.render_type)
            if ok:
                review = ReviewResult(
                    optimized_code=code,
                    changed=False,
                    review_notes="Passed local validation.",
                )
            else:
                review = await pipeline.run_repair(
                    user_input=user_input,
                    analysis=analysis,
                    code=code,
                    error=validation_error,
                )
        except Exception as exc:
            logger.warning(f"FigureGenerator failed: {exc}", exc_info=True)
            raise GenerationFailure(f"figure generation failed: {exc}") from exc

        final_code = review.optimized_code or code
        render_type = analysis.render_type
        final_ok, residual_error = validate_visualization(final_code, render_type)
        if not final_ok:
            raise GenerationFailure(f"figure failed validation after repair: {residual_error}")
        lang_tag = {
            "svg": "svg",
            "mermaid": "mermaid",
            "chartjs": "javascript",
        }.get(render_type, "svg")

        return (
            {
                "render_type": render_type,
                "code": {"language": lang_tag, "content": final_code},
                "description": analysis.description,
                "chart_type": analysis.chart_type,

View on GitHub (pinned to 3e82f13042)

Solutions

1. Check the logged warning traceback (exc_info=True) to identify the underlying exc — it names the real cause
2. Fix provider-level issues first: API key, rate limit, network, model name
3. Retry the block once; multi-step LLM pipelines fail transiently
4. If it's a parsing failure, use a more capable model or fix the prompt/output-format settings in the figure generator

from deeptutor.services.config.runtime_settings import get_llm_settings
s = get_llm_settings()
assert s.api_key, 'LLM API key missing before figure generation'

try:
    payload, refs, meta = await figure_block.generate(ctx)
except GenerationFailure as exc:
    logger.warning('figure block failed: %s', exc)
    payload = fallback_static_figure(ctx)  # or skip block

When it happens

Trigger: Calling figure _generate when FigureGenerator throws: LLM provider network/auth error, unparseable LLM JSON for analysis/code, missing API key, or an internal bug in the generator's analysis/codegen steps.

Common situations: Expired/missing LLM API key; provider rate limits or timeouts mid multi-step figure generation; model returns markdown-wrapped JSON the generator can't parse; version mismatch between the figure generator package and the block's expected interface.

Related errors

• interactive generation failed: {exc}
• quiz generation failed: {exc}
• animation generation failed: {exc}
• unexpected concept_graph payload type: {type(raw).__name__}
• LLM returned no deep-dive suggestions.

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