HKUDS/DeepTutor · error · GenerationFailure

animation generation failed: {exc}

Error message

animation generation failed: {exc}

What it means

The animation block delegated to the math_animator pipeline and the pipeline raised an arbitrary exception; `_generate` wraps it in `GenerationFailure('animation generation failed: ...')` so the book compiler's retry/fallback machinery can handle it uniformly.

Source

Thrown at deeptutor/book/blocks/animation.py:100

                style_hint=style_hint,
            )
            pipeline = MathAnimatorPipeline(
                api_key=primary_api_key(llm_config.api_key),
                base_url=llm_config.base_url,
                api_version=llm_config.api_version,
                language=ctx.language,
            )
            turn_id = f"book-{ctx.book_id}-{ctx.block.id}"
            result = await pipeline.run(
                turn_id=turn_id,
                user_input=user_input,
                history_context=history_context,
                request_config=request_config,
                attachments=[],
            )
        except Exception as exc:
            logger.warning(f"AnimationGenerator failed: {exc}", exc_info=True)
            raise GenerationFailure(f"animation generation failed: {exc}") from exc

        render_result = result["render_result"]
        summary_payload = result["summary"]
        analysis = result["analysis"]
        artifacts = [artifact.model_dump() for artifact in render_result.artifacts]
        primary = next(
            (
                a
                for a in artifacts
                if a.get("type") == "video" or "video" in (a.get("content_type") or "")
            ),
            artifacts[0] if artifacts else None,
        )

        return (
            {
                "render_type": "video",
                "artifacts": artifacts,

View on GitHub (pinned to 3e82f13042)

Solutions

1. Read the chained cause (`__cause__`) and the logged warning traceback to find the real failure
2. Retry the block — compiler retry paths often succeed on transient LLM failures
3. Simplify the animation request (shorter concept, fewer scenes)
4. Ensure math-animator runtime prerequisites (LaTeX, ffmpeg, fonts) are installed

from deeptutor.book.compiler import GenerationFailure
for attempt in range(2):
    try:
        payload, anchors, meta = await anim_gen._generate(ctx)
        break
    except GenerationFailure as e:
        if attempt == 1 or "math-animator extras" in str(e):
            raise
        logger.warning("retrying animation block: %s", e)

When it happens

Trigger: Any failure inside the `math_animator` capability invoked from the animation block: LLM producing unrunnable Manim code, render-time errors, timeouts, or missing config — all surface here chained from the original exception.

Common situations: Flaky LLM output for Manim scripts; sandbox or LaTeX/font prerequisites missing for manim rendering; API rate limits during code_retry stages; overly complex animation requests.

Related errors

• unexpected concept_graph payload type: {type(raw).__name__}
• LLM returned no deep-dive suggestions.
• LLM did not return any flashcards.
• SectionArchitect produced no subsections in outline pass.
• AnimationGenerator requires the optional math-animator extra

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