run-llama/llama_index · error · ValueError

Module {module_name} not found.

Error message

Module {module_name} not found.

What it means

PromptMixin.update_prompts() splits any ':'-containing key you pass into (module_name, sub_key) and routes the new prompt to the matching entry in _get_prompt_modules(). If the prefix before ':' does not match any registered module name, it raises ValueError(f"Module {module_name} not found.") — the update cannot be routed.

Source

Thrown at llama-index-core/llama_index/core/prompts/mixin.py:77

        """
        prompt_modules = self._get_prompt_modules()

        # update prompts for current module
        self._update_prompts(prompts_dict)

        # get sub-module keys
        # mapping from module name to sub-module prompt keys
        sub_prompt_dicts: Dict[str, PromptDictType] = defaultdict(dict)
        for key in prompts_dict:
            if ":" in key:
                module_name, sub_key = key.split(":")
                sub_prompt_dicts[module_name][sub_key] = prompts_dict[key]

        # now update prompts for submodules
        for module_name, sub_prompt_dict in sub_prompt_dicts.items():
            if module_name not in prompt_modules:
                raise ValueError(f"Module {module_name} not found.")
            module = prompt_modules[module_name]
            module.update_prompts(sub_prompt_dict)

    @abstractmethod
    def _get_prompts(self) -> PromptDictType:
        """Get prompts."""

    @abstractmethod
    def _get_prompt_modules(self) -> PromptMixinType:
        """
        Get prompt sub-modules.

        Return a dictionary of sub-modules within the current module
        that also implement PromptMixin (so that their prompts can also be get/set).

        Can be blank if no sub-modules.

        """

View on GitHub (pinned to afd0fef371)

Solutions

1. Call engine.get_prompts() first and copy the exact flattened keys it prints; pass only those keys to update_prompts().
2. Fix the typo in the module prefix so it matches a key in engine._get_prompt_modules() exactly (case-sensitive).
3. If the target prompt lives on a sub-object you already hold a reference to, update it there directly: engine.response_synthesizer.update_prompts({'text_qa_template': tpl}).
4. Diff against the llama-index version's source (or get_prompts() output) after upgrading — module names occasionally change between releases.

Example fix

# before
engine.update_prompts({
    "retriver:text_qa_template": new_tpl,  # typo: module 'retriver' unknown
})

# after
print(engine.get_prompts().keys())          # shows 'response_synthesizer:text_qa_template'
engine.update_prompts({
    "response_synthesizer:text_qa_template": new_tpl,
})

def safe_update_prompts(engine, new_prompts: dict) -> None:
    known = set(engine.get_prompts().keys())
    unknown = [k for k in new_prompts if k not in known]
    if unknown:
        raise KeyError(
            f"unknown prompt keys {unknown}; available keys: {sorted(known)}"
        )
    engine.update_prompts(new_prompts)

safe_update_prompts(engine, {"response_synthesizer:text_qa_template": tpl})

def is_valid_prompt_update(engine, new_prompts: dict) -> bool:
    return set(new_prompts) <= set(engine.get_prompts().keys())

When it happens

Trigger: Calling engine.update_prompts({'retriver:text_qa_template': tpl}) (typo in module name), or using a module prefix that exists on a different class than the one you're updating, or updating before sub-modules are attached. Any key without ':' is treated as a local prompt key and never triggers this; only prefixed keys do.

Common situations: Copy-pasting update_prompts() snippets from docs of a different engine whose module names differ ('response_synthesizer' vs 'synthesizer'), typos in long flattened keys taken from a get_prompts() dump of another object, version upgrades that renamed internal modules.

Related errors

• Prompt key {key} cannot contain ':'.
• First argument to Readability constructor should be a docume
• Aborting parsing document; {numTags} elements found
• Command failed: {command} {result.stderr}
• Git command failed: {result.stderr}

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/8b1bbd1e665b24ad. Report an issue: GitHub.