HKUDS/DeepTutor · error · ManimRenderError

Visual quality review timed out after {int(self.review_timeo

Error message

Visual quality review timed out after {int(self.review_timeout_seconds)}s.

What it means

Raised by _open_ooxml when zipfile.ZipFile cannot parse the bytes as a ZIP archive (BadZipFile). This helper backs EPUB and all raw-OOXML fallback paths, so it fires when the package is not a zip at all despite its extension.

Source

Thrown at deeptutor/agents/math_animator/retry_manager.py:75

                        f"Starting render attempt {attempt + 1}/{self.max_retries + 1}."
                    )
                render_result = await self.renderer.render(
                    code=code,
                    output_mode=output_mode,
                    quality=quality,
                )
                if self.review_callback is not None:
                    if self.on_status is not None:
                        await self.on_status(
                            "Reviewing rendered visuals for overlap, readability, and framing."
                        )
                    try:
                        review_result = await asyncio.wait_for(
                            self.review_callback(code, render_result),
                            timeout=self.review_timeout_seconds,
                        )
                    except asyncio.TimeoutError as timeout_exc:
                        raise ManimRenderError(
                            f"Visual quality review timed out after {int(self.review_timeout_seconds)}s."
                        ) from timeout_exc
                    render_result.visual_review = review_result
                    if not review_result.passed:
                        if attempt >= self.max_retries:
                            if self.on_status is not None:
                                await self.on_status(
                                    "Visual review still found issues after all retries. Returning the best available result with a warning."
                                )
                            render_result.retry_attempts = len(retry_history)
                            render_result.retry_history = retry_history
                            return code, render_result
                        retry_attempt = RetryAttempt(
                            attempt=attempt + 1,
                            error=(
                                "Visual review failed: "
                                + (
                                    review_result.summary

View on GitHub (pinned to 3e82f13042)

Solutions

Verify magic bytes before extraction (the module's _check_magic should catch most; ensure callers use it)
Convert legacy formats to OOXML with LibreOffice
Re-download the authentic file if it's an HTML error page in disguise

Example fix

// before
text = _extract_docx_ooxml(data, "notazip.docx")  # raises

// after
if not data.startswith(b"PK"):
    raise ValueError("not an OOXML package")
text = _extract_docx_ooxml(data, "ok.docx")

Defensive patterns

Strategy: type-guard

Validate before calling

def is_zip_package(data: bytes) -> bool:
    return data[:2] == b"PK"

Type guard

def is_zip_package(data: bytes) -> bool:
    return data[:2] == b"PK"

Try / catch

except CorruptDocumentError as e:
    if "failed to open Office ZIP package" in str(e):
        convert_legacy_format(fn) and retry

Prevention

Always magic-byte check before OOXML parsing
Never trust extensions alone; legacy renames are the top cause

When it happens

Trigger: Passing a .docx/.xlsx/.pptx/.epub whose bytes are actually plain binary, OLE2 (legacy .doc/.xls), or truncated; a fallback path invoked after the primary parser already failed on non-zip data.

Common situations: Renamed legacy Office files, mislabeled downloads, HTML error pages saved with document extensions.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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