{"record":{"id":"a4fc2b72f9eb2432","repo":"666ghj/MiroFish","slug":"zep-api-key","errorCode":null,"errorMessage":"ZEP_API_KEY 未配置","messagePattern":"ZEP_API_KEY 未配置","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"backend/app/services/graph_builder.py","lineNumber":70,"sourceCode":"class BatchSubmission:\n    \"\"\"Durable identity for one Zep Batch API ingestion operation.\"\"\"\n\n    batch_id: str\n    operation_id: str\n    episode_uuids: List[str]\n    item_count: int\n\n\nclass GraphBuilderService:\n    \"\"\"\n    图谱构建服务\n    负责调用Zep API构建知识图谱\n    \"\"\"\n    \n    def __init__(self, api_key: Optional[str] = None):\n        self.api_key = api_key or Config.ZEP_API_KEY\n        if not self.api_key:\n            raise ValueError(\"ZEP_API_KEY 未配置\")\n        \n        self.client = get_zep_client(self.api_key)\n        self.task_manager = TaskManager()\n    \n    def build_graph_async(\n        self,\n        text: str,\n        ontology: Dict[str, Any],\n        graph_name: str = \"MiroFish Graph\",\n        chunk_size: int = 500,\n        chunk_overlap: int = 50,\n        batch_size: int = 350\n    ) -> str:\n        \"\"\"\n        异步构建图谱\n        \n        Args:\n            text: 输入文本","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/app/services/graph_builder.py#L52-L88","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set ZEP_API_KEY in backend/.env (or the deployment environment) and restart the backend.","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.","In containerized deploys, verify the secret is mounted (env | grep ZEP inside the container) before restart.","For tests, inject the key explicitly: GraphBuilderService(api_key='test-key') with a mocked client."],"exampleFix":"# before\nself.api_key = api_key or Config.ZEP_API_KEY\nif not self.api_key:\n    raise ValueError(\"ZEP_API_KEY 未配置\")\n\n# after - fail at app startup with an actionable message instead of per-request\n# settings.py\nZEP_API_KEY: str = Field(..., alias=\"ZEP_API_KEY\")  # pydantic: missing key aborts boot\n# graph_builder.py\nself.api_key = api_key or Config.ZEP_API_KEY\nif not self.api_key:\n    raise ValueError(\"ZEP_API_KEY is not configured; set it in the environment or backend/.env\")","handlingStrategy":"validation","validationCode":"key = api_key or Config.ZEP_API_KEY\nif not key:\n    raise RuntimeError('ZEP_API_KEY is missing; set it in backend/.env or the deployment environment')\nservice = GraphBuilderService(api_key=key)","typeGuard":null,"tryCatchPattern":"try:\n    builder = GraphBuilderService()\nexcept ValueError as e:\n    if 'ZEP_API_KEY' in str(e):\n        logger.error('Zep credentials not configured; graph build unavailable')\n        raise HTTPException(status_code=503, detail='Graph service is not configured') from e\n    raise","preventionTips":["Fail fast at process startup if ZEP_API_KEY is required in this deployment (e.g. pydantic required field).","Add a startup/healthcheck endpoint that verifies required config including ZEP_API_KEY.","Verify the secret is mounted inside containers (env | grep ZEP) after each deploy.","In tests, always pass api_key explicitly with a mocked client."],"tags":["backend","python","configuration","zep","missing-key"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}