{"record":{"id":"a6932bc6fb5ab960","repo":"666ghj/MiroFish","slug":"zep-api-url-is-unsupported-unset-it-to-use-zep-cl","errorCode":null,"errorMessage":"ZEP_API_URL is unsupported; unset it to use Zep Cloud","messagePattern":"ZEP_API_URL is unsupported; unset it to use Zep Cloud","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/app/utils/zep.py","lineNumber":72,"sourceCode":"\n\n@lru_cache(maxsize=4)\ndef _cached_zep_client(api_key: str, timeout: float) -> Zep:\n    return Zep(\n        api_key=api_key,\n        base_url=ZEP_CLOUD_BASE_URL,\n        timeout=timeout,\n    )\n\n\ndef get_zep_client(api_key: str | None = None, timeout: float | None = None) -> Zep:\n    \"\"\"Return a process-shared, explicitly configured Zep Cloud client.\"\"\"\n\n    # zep-cloud gives ZEP_API_URL precedence even when base_url is explicit.\n    # Reject it so this Cloud-only integration cannot silently target a\n    # self-hosted or compatibility endpoint.\n    if os.environ.get(\"ZEP_API_URL\"):\n        raise ValueError(\"ZEP_API_URL is unsupported; unset it to use Zep Cloud\")\n\n    normalized_key = (api_key or Config.ZEP_API_KEY or \"\").strip()\n    if not normalized_key:\n        raise ValueError(\"ZEP_API_KEY 未配置\")\n\n    request_timeout = float(\n        timeout if timeout is not None else ZEP_HTTP_REQUEST_TIMEOUT_SECONDS\n    )\n    if request_timeout <= 0:\n        raise ValueError(\"Zep request timeout must be greater than 0\")\n    return _cached_zep_client(normalized_key, request_timeout)\n\n\ndef clear_zep_client_cache() -> None:\n    \"\"\"Clear cached clients. Intended for tests and controlled reconfiguration.\"\"\"\n\n    _cached_zep_client.cache_clear()\n","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/app/utils/zep.py#L54-L90","documentation":"Raised by get_zep_client in backend/app/utils/zep.py when os.environ.get(\"ZEP_API_URL\") is truthy. The comment in the source explains why: zep-cloud gives ZEP_API_URL precedence even when base_url is explicit (the client is built with base_url=ZEP_CLOUD_BASE_URL), so this Cloud-only integration rejects the variable to prevent silently targeting a self-hosted/compatibility endpoint. Note an empty-string value does not trigger it (falsy check).","triggerScenarios":"ZEP_API_URL set to any non-empty value in the shell, .env, Docker/Kubernetes env, or CI secrets while get_zep_client() is called — e.g. ZEP_API_URL=http://localhost:8000 left over from self-hosted Zep.","commonSituations":"Migrating from open-source Zep to Zep Cloud and forgetting to remove ZEP_API_URL; a shared .env mixing OSS and Cloud settings; a deployment manifest copied from a self-hosted setup.","solutions":["Unset the variable (unset ZEP_API_URL) and remove it from .env, docker-compose environment:, and K8s ConfigMap/Secret refs — any one non-empty occurrence triggers this.","Search the whole environment chain (shell profile, .env files, container specs) if the source is not obvious.","If you actually need self-hosted Zep, this integration does not support it — do not bypass the guard; use a separate code path with the OSS client."],"exampleFix":"# before (.env)\nZEP_API_URL=http://localhost:8000\nZEP_API_KEY=...\n\n# after (.env)\nZEP_API_KEY=...","handlingStrategy":"validation","validationCode":"import os\n\ndef zep_env_is_clean() -> bool:\n    return not os.environ.get(\"ZEP_API_URL\")","typeGuard":null,"tryCatchPattern":"try:\n    client = get_zep_client()\nexcept ValueError as e:\n    if \"ZEP_API_URL\" in str(e):\n        os.environ.pop(\"ZEP_API_URL\", None)\n        client = get_zep_client()  # retry with cleaned env\n    else:\n        raise","preventionTips":["Audit .env and deploy manifests for ZEP_API_URL after migrating from self-hosted Zep to Cloud.","Add a startup assertion in dev that fails fast with a clear message if ZEP_API_URL is set.","Keep a single source of truth for Zep env vars; document that this integration is Cloud-only."],"tags":["configuration","environment","zep","cloud-migration"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}