HKUDS/DeepTutor · error · ValueError

Invalid math animator config: {details}

Error message

Invalid math animator config: {details}

What it means

DocumentTooLargeError raised when a member's file_size/compress_size ratio exceeds _EPUB_MAX_COMPRESSION_RATIO — a classic zip-bomb signature. Even if absolute sizes are small, an extreme expansion ratio signals maliciously crafted compression.

Source

Thrown at deeptutor/agents/math_animator/request_config.py:32

    quality: Literal["low", "medium", "high"] = "medium"
    style_hint: str = Field(default="", max_length=500)


def validate_math_animator_request_config(
    raw_config: dict[str, Any] | None,
) -> MathAnimatorRequestConfig:
    if raw_config is None:
        return MathAnimatorRequestConfig()
    if not isinstance(raw_config, dict):
        raise ValueError("Math animator config must be an object.")
    try:
        return MathAnimatorRequestConfig.model_validate(raw_config)
    except ValidationError as exc:
        details = "; ".join(
            f"{'.'.join(str(part) for part in error['loc'])}: {error['msg']}"
            for error in exc.errors()
        )
        raise ValueError(f"Invalid math animator config: {details}") from exc


__all__ = [
    "MathAnimatorRequestConfig",
    "validate_math_animator_request_config",
]

View on GitHub (pinned to 3e82f13042)

Solutions

1. If legitimate, re-zip the EPUB without the extreme-ratio member (often padding/junk)
2. If from an untrusted source, reject the file outright
3. Catch DocumentTooLargeError at the ingestion boundary and log/alert on it as a potential attack

Example fix

// before
text = extract_text_from_bytes(data, filename="suspicious.epub")  # raises

// after
import zipfile
zf = zipfile.ZipFile(io.BytesIO(data))
# audit ratios, strip offending members, rebuild, then extract

import zipfile, io
zf = zipfile.ZipFile(io.BytesIO(data))
if any(i.compress_size and i.file_size / i.compress_size > 100 for i in zf.infolist()):
    quarantine(fn, "possible zip bomb")

except DocumentTooLargeError as e:
    if "compression ratio" in str(e):
        quarantine_and_alert(fn)

When it happens

Trigger: A member with e.g. 1KB compressed / 500MB declared uncompressed; crafted archives designed to evade absolute-size checks while still exploding on extraction.

Common situations: Adversarial uploads to public ingestion endpoints; rarely, unusual but legitimate highly-repetitive content (padding files) triggering false positives.

Related errors

• Rendered {suffix} artifact not found.
• Generated code does not define a renderable Manim Scene clas
• Math animator config must be an object.
• MinerU archive has too many entries ({len(members)}).
• Code repair attempt #{attempt + 1} timed out after {int(self

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