666ghj/MiroFish · critical · ValueError

ZEP_API_KEY 未配置

Error message

ZEP_API_KEY 未配置

What it means

ValueError raised in GraphBuilderService.__init__ (backend/app/services/graph_builder.py) when neither the constructor argument nor Config.ZEP_API_KEY provides an API key. The service cannot construct a Zep client without credentials, so it fails fast before any network call. The message is in Chinese ('ZEP_API_KEY not configured').

Source

Thrown at backend/app/services/graph_builder.py:70

class BatchSubmission:
    """Durable identity for one Zep Batch API ingestion operation."""

    batch_id: str
    operation_id: str
    episode_uuids: List[str]
    item_count: int


class GraphBuilderService:
    """
    图谱构建服务
    负责调用Zep API构建知识图谱
    """
    
    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)
        self.task_manager = TaskManager()
    
    def build_graph_async(
        self,
        text: str,
        ontology: Dict[str, Any],
        graph_name: str = "MiroFish Graph",
        chunk_size: int = 500,
        chunk_overlap: int = 50,
        batch_size: int = 350
    ) -> str:
        """
        异步构建图谱
        
        Args:
            text: 输入文本

View on GitHub (pinned to b5b53acc57)

Solutions

1. Set ZEP_API_KEY in backend/.env (or the deployment environment) and restart the backend.
2. Confirm Config actually loads it: check the Config class reads ZEP_API_KEY from the same env source (os.environ vs pydantic BaseSettings) at import time.
3. In containerized deploys, verify the secret is mounted (env | grep ZEP inside the container) before restart.
4. For tests, inject the key explicitly: GraphBuilderService(api_key='test-key') with a mocked client.

Example fix

# before
self.api_key = api_key or Config.ZEP_API_KEY
if not self.api_key:
    raise ValueError("ZEP_API_KEY 未配置")

# after - fail at app startup with an actionable message instead of per-request
# settings.py
ZEP_API_KEY: str = Field(..., alias="ZEP_API_KEY")  # pydantic: missing key aborts boot
# graph_builder.py
self.api_key = api_key or Config.ZEP_API_KEY
if not self.api_key:
    raise ValueError("ZEP_API_KEY is not configured; set it in the environment or backend/.env")

key = api_key or Config.ZEP_API_KEY
if not key:
    raise RuntimeError('ZEP_API_KEY is missing; set it in backend/.env or the deployment environment')
service = GraphBuilderService(api_key=key)

try:
    builder = GraphBuilderService()
except ValueError as e:
    if 'ZEP_API_KEY' in str(e):
        logger.error('Zep credentials not configured; graph build unavailable')
        raise HTTPException(status_code=503, detail='Graph service is not configured') from e
    raise

When it happens

Trigger: Instantiating GraphBuilderService (directly or via graph build/delete endpoints) with ZEP_API_KEY absent from the environment/.env; Config loaded before the .env file is read; key present under a different name (e.g. ZEP_APIKEY); deployment secret not mounted in the container.

Common situations: Fresh clone without .env setup; Docker/K8s secret not wired so the env var is empty in the container; CI runs lacking the secret; .env not copied in production deploy; Config class renamed the field.

Related errors

• Graph {graph_id} is in use by active consumer(s): {', '.join
• Persisted Zep batch does not match the current graph input
• Zep batch list cursor did not advance
• Multiple Zep batches match operation {operation_id}; refusin
• graph_id is required

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