HKUDS/DeepTutor · error · RuntimeError

Prompt key '{key}' missing or empty in loaded book prompt bu

Error message

Prompt key '{key}' missing or empty in loaded book prompt bundle.

What it means

`get_book_prompt(key)` found that the loaded YAML prompt bundle for the current language has no entry for `key`, or the entry is empty/whitespace. It is a RuntimeError signalling broken prompt-pack packaging rather than a bad key supplied by user code in most cases.

Source

Thrown at deeptutor/book/blocks/_prompts.py:63

        agent_name=name,
        language=language,
    )
    if not prompts:
        raise RuntimeError(
            f"Missing prompt bundle for book/{name} (language={language}). "
            f"Expected deeptutor/book/prompts/{{en,zh}}/{name}.yaml."
        )
    return prompts


def get_book_prompt(prompts: dict[str, Any], key: str) -> str:
    """Return the prompt string under ``key`` from a loaded bundle.

    Raises ``RuntimeError`` if the key is missing or not a non-empty string.
    """
    value = prompts.get(key)
    if not isinstance(value, str) or not value.strip():
        raise RuntimeError(f"Prompt key '{key}' missing or empty in loaded book prompt bundle.")
    return value


__all__ = ["load_book_prompts", "get_book_prompt"]

View on GitHub (pinned to 3e82f13042)

Solutions

1. Inspect the loaded bundle (load_book_prompts output) and confirm which keys exist for the current language
2. Add/translate the missing key in the language's prompt YAML
3. Align code and bundles in the same commit; add a test asserting key parity across languages (the repo already has tests iterating every visual block's brief per language)

Example fix

# before
# zh bundle missing 'animation_brief'
text = get_book_prompt("animation_brief")

# after: add to zh prompts YAML
animation_brief: |
  为动画块撰写简短说明…

from deeptutor.book.blocks._prompts import load_book_prompts
bundle = load_book_prompts(lang)
missing = required_keys - set(bundle)
if missing:
    raise ConfigError(f"prompt bundle {lang} missing: {missing}")

def has_prompt(bundle: dict, key: str) -> bool:
    v = bundle.get(key)
    return isinstance(v, str) and bool(v.strip())

try:
    text = get_book_prompt(key)
except RuntimeError:
    text = DEFAULT_PROMPTS[key]  # fallback copy

When it happens

Trigger: Calling `get_book_prompt('some_key')` where the language-specific YAML under the book prompt bundles lacks that key; adding a new prompt key in code before adding it to en/zh YAML; a malformed YAML file that silently drops sections; loading the wrong bundle path.

Common situations: Adding a new book block or stage that needs a fresh prompt without updating both language bundles; renaming a key in code but not in YAML; translation files lagging behind the English bundle after a version bump.

Related errors

• No embedding model is configured. Set up the embedding profi
• {exc}
• No endpoint URL configured for image generation.
• No endpoint URL configured for image generation.
• KeyPool requires at least one non-empty key

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