666ghj/MiroFish · error · ValueError

ZEP_API_KEY 未配置

Error message

ZEP_API_KEY 未配置

What it means

ZepEntityReader.__init__ requires a Zep API key: it falls back from the constructor argument to Config.ZEP_API_KEY, and if neither is set it raises ValueError('ZEP_API_KEY 未配置') before creating the Zep client. Every entity/graph read this service performs is blocked until the key is supplied.

Source

Thrown at backend/app/services/zep_entity_reader.py:83

            "total_count": self.total_count,
            "filtered_count": self.filtered_count,
        }


class ZepEntityReader:
    """
    Zep实体读取与过滤服务
    
    主要功能：
    1. 从Zep图谱读取所有节点
    2. 筛选出符合预定义实体类型的节点（Labels不只是Entity的节点）
    3. 获取每个实体的相关边和关联节点信息
    """
    
    def __init__(self, api_key: Optional[str] = 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)
    
    def _call_with_retry(
        self, 
        func: Callable[[], T], 
        operation_name: str,
        max_retries: int = 3,
        initial_delay: float = 2.0
    ) -> T:
        """
        带重试机制的Zep API调用
        
        Args:
            func: 要执行的函数（无参数的lambda或callable）
            operation_name: 操作名称，用于日志
            max_retries: 最大重试次数（默认3次，即最多尝试3次）
            initial_delay: 初始延迟秒数

View on GitHub (pinned to b5b53acc57)

Solutions

1. Set ZEP_API_KEY in the backend environment (.env or secret manager) and restart the backend.
2. Alternatively pass api_key explicitly: ZepEntityReader(api_key=os.environ['ZEP_TOKEN']).
3. Verify with a minimal snippet that Config.ZEP_API_KEY loads (non-empty) before starting dependent jobs.

Example fix

# before
reader = ZepEntityReader()  # ValueError: ZEP_API_KEY 未配置

# after
# .env
ZEP_API_KEY=zep_live_xxxxxxxx
reader = ZepEntityReader()

def zep_key_configured() -> bool:
    return bool(Config.ZEP_API_KEY)

try:
    reader = ZepEntityReader()
except ValueError as e:
    if "ZEP_API_KEY" in str(e):
        raise HTTPException(503, detail="graph analysis unavailable: ZEP not configured")
    raise

When it happens

Trigger: Instantiating ZepEntityReader() (directly or via a graph-analysis endpoint) in an environment where the ZEP_API_KEY env var / config entry is unset or empty and no api_key argument is passed.

Common situations: Missing entry in .env / deployment secrets; CI runs without Zep credentials; key name typo (ZEP_APIKEY, ZEP_KEY); empty-string value counts as unset.

Related errors

• ZEP_API_KEY未配置
• ZEP_API_KEY 未配置
• ZEP_API_KEY must be supplied through the process environment
• ZEP_API_KEY 未配置
• 启用图谱记忆更新时必须提供 graph_id

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