{"record":{"id":"7501dc5ba00384c4","repo":"HKUDS/DeepTutor","slug":"prompt-key-key-missing-or-empty-in-loaded-book","errorCode":null,"errorMessage":"Prompt key '{key}' missing or empty in loaded book prompt bundle.","messagePattern":"Prompt key '(.+?)' missing or empty in loaded book prompt bundle\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"deeptutor/book/blocks/_prompts.py","lineNumber":63,"sourceCode":"        agent_name=name,\n        language=language,\n    )\n    if not prompts:\n        raise RuntimeError(\n            f\"Missing prompt bundle for book/{name} (language={language}). \"\n            f\"Expected deeptutor/book/prompts/{{en,zh}}/{name}.yaml.\"\n        )\n    return prompts\n\n\ndef get_book_prompt(prompts: dict[str, Any], key: str) -> str:\n    \"\"\"Return the prompt string under ``key`` from a loaded bundle.\n\n    Raises ``RuntimeError`` if the key is missing or not a non-empty string.\n    \"\"\"\n    value = prompts.get(key)\n    if not isinstance(value, str) or not value.strip():\n        raise RuntimeError(f\"Prompt key '{key}' missing or empty in loaded book prompt bundle.\")\n    return value\n\n\n__all__ = [\"load_book_prompts\", \"get_book_prompt\"]\n","sourceCodeStart":45,"sourceCodeEnd":68,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/book/blocks/_prompts.py#L45-L68","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the loaded bundle (load_book_prompts output) and confirm which keys exist for the current language","Add/translate the missing key in the language's prompt YAML","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)"],"exampleFix":"# before\n# zh bundle missing 'animation_brief'\ntext = get_book_prompt(\"animation_brief\")\n\n# after: add to zh prompts YAML\nanimation_brief: |\n  为动画块撰写简短说明…","handlingStrategy":"validation","validationCode":"from deeptutor.book.blocks._prompts import load_book_prompts\nbundle = load_book_prompts(lang)\nmissing = required_keys - set(bundle)\nif missing:\n    raise ConfigError(f\"prompt bundle {lang} missing: {missing}\")","typeGuard":"def has_prompt(bundle: dict, key: str) -> bool:\n    v = bundle.get(key)\n    return isinstance(v, str) and bool(v.strip())","tryCatchPattern":"try:\n    text = get_book_prompt(key)\nexcept RuntimeError:\n    text = DEFAULT_PROMPTS[key]  # fallback copy","preventionTips":["Keep en and zh prompt YAML key-parity; test both languages in CI","Add a startup assertion that all keys consumed by code exist in every bundle","Validate bundles right after load, not at first use"],"tags":["i18n","prompts","configuration","yaml"],"backgroundTag":"missing-translation-key","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}