bytedance/deer-flow · error · FileNotFoundError

chat prompt template not found: {name} (searched: {searched}

Error message

chat prompt template not found: {name} (searched: {searched})

What it means

FileNotFoundError from the deermem prompt loader: no candidate path contained a prompt template with the requested name. The message lists every searched path, so you can see exactly which directories were scanned. Module-level aliases (staleness_review, consolidation, fact_extraction) load at import, so a bad search path breaks import of the prompt module itself.

Source

Thrown at backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/prompt.py:177

                raise PromptConfigurationError(f"Invalid YAML in {path}: {e}") from e
            data = data or {}
            fmt = data.get("format", "chat")
            if fmt != "chat":
                raise PromptConfigurationError(f"Expected format='chat' in {path}, got {fmt!r}; use load_prompt() for text-format templates")
            msg_list = data.get("messages")
            if not isinstance(msg_list, list) or not msg_list:
                raise PromptConfigurationError(f"Missing or empty 'messages' key in {path}")
            raw_templates: list[dict[str, str]] = []
            for msg in msg_list:
                role = msg.get("role", "user")
                content = msg.get("content", "")
                if not isinstance(content, str):
                    content = str(content)
                raw_templates.append({"role": role, "content": content})
            _CHAT_TEMPLATE_CACHE[cache_key] = (raw_templates, str(path))
            return _render_messages(raw_templates, variables, str(path))
    searched = ", ".join(str(c) for c in candidates)
    raise FileNotFoundError(f"chat prompt template not found: {name} (searched: {searched})")


# Module-level aliases for the injected text sections (staleness_review /
# consolidation / fact_extraction). Each loads its bundled yaml template once
# at import. ``memory_update`` is NOT here -- it uses the chat form via
# :func:`load_prompt_messages` (system/user split, mirroring the lead agent's
# static system prompt).
STALENESS_REVIEW_PROMPT = load_prompt("staleness_review")
CONSOLIDATION_PROMPT = load_prompt("consolidation")
FACT_EXTRACTION_PROMPT = load_prompt("fact_extraction")


# Module-level tiktoken encoding cache.  Populated lazily on first use;
# subsequent calls are a dict lookup (no network I/O).  Pre-warming at
# startup via :func:`warm_tiktoken_cache` avoids blocking a request on the
# (potentially slow) first ``get_encoding`` call.
#
# A *failed* load is cached as a ``(None, monotonic_timestamp)`` tuple so that

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Check the '(searched: ...)' paths in the message; place <name>.yaml in one of them.
2. Fix typos/casing in the requested name.
3. If packaging, ensure the prompt YAML files are declared as package data and present in the installed wheel.
4. For custom templates, point the loader's search directory at the folder containing your YAML files.

Example fix

# before
PROMPT = load_prompt("stalness_review")  # typo

# after
PROMPT = load_prompt("staleness_review")

from pathlib import Path

def prompt_exists(name, search_dirs) -> bool:
    return any((d / f'{name}.yaml').is_file() for d in search_dirs)

assert prompt_exists('staleness_review', prompt_dirs), 'bundled prompt missing — check packaging'

try:
    p = load_prompt('consolidation')
except FileNotFoundError as e:
    # message lists searched paths — verify packaging/deployment includes prompt YAMLs
    raise RuntimeError(f'prompt data files missing from deployment: {e}') from e

When it happens

Trigger: load_prompt(name)/load_prompt_messages(name) where no <searched-dir>/<name>.yaml exists: wrong name/typo, missing prompts package data (wheel installed without data files), or a custom prompt_dir that does not contain the file.

Common situations: Packaging issue: package built without including bundled YAML templates (missing package_data); custom deployment that moves prompt files; renaming a prompt without updating callers; name casing mismatch on case-sensitive filesystems.

Related errors

• Missing or empty 'messages' key in {path}
• guaranteed_categories must be an iterable of strings, not a
• memory update queue is full (depth {len(self._items)} >= {ma
• retrieval scope userId must be a string or null
• retrieval scope agentName must be a string or null

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/332fc647807d5c1c. Report an issue: GitHub.