666ghj/MiroFish · error · ValueError

ZEP_API_KEY 未配置

Error message

ZEP_API_KEY 未配置

What it means

ValueError raised in ZepTools.__init__ when neither the constructor argument api_key nor Config.ZEP_API_KEY is set. The tools wrapper requires a Zep Cloud API key to construct its client (get_zep_client), so initialization refuses to proceed rather than failing later on every request.

Source

Thrown at backend/app/services/zep_tools.py:433

    
    【基础工具】
    - search_graph - 图谱语义搜索
    - get_all_nodes - 获取图谱所有节点
    - get_all_edges - 获取图谱所有边（含时间信息）
    - get_node_detail - 获取节点详细信息
    - get_node_edges - 获取节点相关的边
    - get_entities_by_type - 按类型获取实体
    - get_entity_summary - 获取实体的关系摘要
    """
    
    # 重试配置
    MAX_RETRIES = 3
    RETRY_DELAY = 2.0
    
    def __init__(self, api_key: Optional[str] = None, llm_client: Optional[LLMClient] = None):
        self.api_key = api_key or Config.ZEP_API_KEY
        if not self.api_key:
            raise ValueError("ZEP_API_KEY 未配置")
        
        self.client = get_zep_client(self.api_key)
        # LLM客户端用于InsightForge生成子问题
        self._llm_client = llm_client
        logger.info(t("console.zepToolsInitialized"))
    
    @property
    def llm(self) -> LLMClient:
        """延迟初始化LLM客户端"""
        if self._llm_client is None:
            self._llm_client = LLMClient()
        return self._llm_client
    
    def _call_with_retry(self, func, operation_name: str, max_retries: int = None):
        """Retry one safe read using typed Zep/HTTPX error classification."""

        return call_zep_read_with_retry(
            func,

View on GitHub (pinned to b5b53acc57)

Solutions

1. Set ZEP_API_KEY in the environment or config file used by Config before constructing ZepTools
2. Pass api_key explicitly: ZepTools(api_key=os.environ['ZEP_API_KEY'])
3. Fail fast at startup: validate required config keys once during boot instead of at first use

Example fix

# before
tools = ZepTools()  # ZEP_API_KEY unset -> ValueError

# after
api_key = os.environ.get("ZEP_API_KEY")
if not api_key:
    raise SystemExit("ZEP_API_KEY is required")
tools = ZepTools(api_key=api_key)

if not (api_key or Config.ZEP_API_KEY):
    raise SystemExit("ZEP_API_KEY is required before using Zep tools")

try:
    tools = ZepTools(api_key=key)
except ValueError as e:
    logger.error("config error: %s", e)
    raise

When it happens

Trigger: Instantiating ZepTools() (or anything that constructs it, e.g. graph search tooling) in an environment where the ZEP_API_KEY environment variable/config entry is absent or empty string.

Common situations: Missing .env entry, deployment where env vars are not passed to the container/process, CI runs without secrets, or a typo in the variable name in Config.

Related errors

• LLM_API_KEY 未配置
• ZEP_API_KEY 未配置
• ZEP_API_KEY 未配置
• ZEP_API_KEY未配置
• ZEP_API_URL is unsupported; unset it to use Zep Cloud

AI-assisted analysis of 666ghj/MiroFish@b5b53acc57 (2026-08-14). Data as JSON: /api/errors/2d58ea70e4fa8d12. Report an issue: GitHub.