HKUDS/DeepTutor · error · GenerationFailure

quiz generation failed: {exc}

Error message

quiz generation failed: {exc}

What it means

The quiz block wraps the QuizGenerator call in try/except; any exception it throws (LLM/provider errors, internal quiz pipeline failures) is re-raised as GenerationFailure('quiz generation failed: ...') with the original exception chained and logged as a warning with traceback.

Source

Thrown at deeptutor/book/blocks/quiz.py:68

            pipeline = QuestionPipeline(language=ctx.language, kb_name=effective_kb)
            result = await pipeline.run(
                context=UnifiedContext(
                    session_id=f"book-{ctx.book_id}",
                    user_message=topic,
                    active_capability="deep_question",
                    knowledge_bases=[effective_kb] if effective_kb else [],
                    language=ctx.language,
                ),
                user_message=topic,
                num_questions=max(1, int(num_questions or 1)),
                difficulty=difficulty,
                question_types=question_types,
                stream=get_book_bus(ctx.book_id),
            )
            summary = dict(result.get("summary") or {})
        except Exception as exc:
            logger.warning(f"QuizGenerator failed: {exc}", exc_info=True)
            raise GenerationFailure(f"quiz generation failed: {exc}") from exc

        questions = self._extract_questions(summary)
        if not questions:
            raise GenerationFailure("no questions generated")

        return (
            {"questions": questions, "topic": topic},
            [],
            {
                "completed": summary.get("completed", 0),
                "failed": summary.get("failed", 0),
                "kb": ctx.primary_kb,
            },
        )

    @staticmethod
    def _extract_questions(summary: dict[str, Any]) -> list[dict[str, Any]]:
        results = summary.get("results") or []

View on GitHub (pinned to 3e82f13042)

Solutions

1. Check the logged warning traceback for the root exc
2. Resolve provider issues (key, quota, network) first
3. Retry the quiz block — multi-step LLM loops fail transiently
4. Verify ctx (topic, rag context, book_id bus) is populated before invoking

assert llm_client_ready(), 'LLM provider unavailable before quiz generation'
assert topic and topic.strip(), 'quiz requires a non-empty topic'

try:
    return await quiz_block.generate(ctx)
except GenerationFailure as exc:
    logger.warning('quiz failed: %s (cause: %s)', exc, exc.__cause__)
    return fallback_quiz(ctx)  # cached/static quiz or skip

When it happens

Trigger: Calling quiz _generate when QuizGenerator raises — LLM auth/network/rate-limit errors, failures inside its multi-question generation loop (it receives question_types and the book stream bus), or context problems passed via ctx (e.g. missing KB).

Common situations: Expired API key; rate limits during multi-question generation; RagContext/topic empty causing internal assertion; stream bus errors; QuizGenerator package API changed between versions.

Related errors

• figure generation failed: {exc}
• interactive generation failed: {exc}
• no questions generated
• animation generation failed: {exc}
• unexpected concept_graph payload type: {type(raw).__name__}

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