{"record":{"id":"e546b793136cef69","repo":"HKUDS/DeepTutor","slug":"pageindex-oss-requires-a-resolved-local-library-pa","errorCode":null,"errorMessage":"PageIndex OSS requires a resolved Local Library path","messagePattern":"PageIndex OSS requires a resolved Local Library path","errorType":"error_code","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/rag/pipelines/pageindex/pipeline.py","lineNumber":81,"sourceCode":"        *,\n        client: Optional[PageIndexClient] = None,\n        config_provider=None,\n        provider: str = storage.CLOUD_PROVIDER,\n    ) -> None:\n        self.logger = logging.getLogger(__name__)\n        self.kb_base_dir = kb_base_dir or DEFAULT_KB_BASE_DIR\n        self._client = client\n        self._config_provider = config_provider or get_pageindex_config\n        self.provider = (\n            storage.OSS_PROVIDER if provider == storage.OSS_PROVIDER else storage.CLOUD_PROVIDER\n        )\n\n    def _get_client(self, storage_dir: Path | None = None) -> PageIndexClient:\n        if self._client is not None:\n            return self._client\n        if self.provider == storage.OSS_PROVIDER:\n            if storage_dir is None:\n                raise RuntimeError(\"PageIndex OSS requires a resolved Local Library path\")\n            return PageIndexClient.local(storage.sdk_storage_path(storage_dir))\n        return PageIndexClient.cloud(self._config_provider())\n\n    def _processing_mode(self, kb_name: str) -> str | None:\n        if self.provider != storage.OSS_PROVIDER:\n            return None\n        try:\n            from deeptutor.services.config.knowledge_base_config import KnowledgeBaseConfigService\n\n            mode = (\n                str(\n                    KnowledgeBaseConfigService.get_instance(\n                        Path(self.kb_base_dir) / \"kb_config.json\"\n                    )\n                    .get_kb_config(kb_name)\n                    .get(\"pageindex_mode\")\n                    or \"\"\n                )","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/rag/pipelines/pageindex/pipeline.py#L63-L99","documentation":"The PageIndex pipeline was asked to build an OSS (local library) client but no storage directory was supplied. _get_client requires a resolved Local Library path for the OSS provider because the local SDK must be pointed at an on-disk storage root.","triggerScenarios":"Pipeline._get_client(storage_dir=None) while self.provider == storage.OSS_PROVIDER — e.g. ingest/delete/remove_document called before a Local Library storage dir was resolved from the KB directory.","commonSituations":"KB created in cloud mode then switched to OSS provider; ingest attempted before document upload established a storage dir; corrupt/missing KB metadata so resolve_storage_dir returns None; newer pipeline version that added the storage_dir parameter called from old code paths.","solutions":["Ensure the KB has an active Local Library version directory (run ingest through the normal upload flow so storage_dir is resolved)","Check resolve_kb_dir/resolve_storage_dir output for the KB and repair or recreate the KB if metadata is missing","Pass an explicit storage_dir argument when calling _ingest/delete/remove_document on the OSS provider"],"exampleFix":"# before\nclient = pipeline._get_client()  # RuntimeError for OSS\n# after\nclient = pipeline._get_client(storage_dir=kb_storage_dir)","handlingStrategy":"validation","validationCode":"storage_dir = resolve_storage_dir_for_read(kb_dir, None)\nif storage_dir is None:\n    raise ValueError(\"KB has no local library yet; ingest first\")\nclient = pipeline._get_client(storage_dir)","typeGuard":null,"tryCatchPattern":"try:\n    client = pipeline._get_client(storage_dir)\nexcept RuntimeError as e:\n    if \"Local Library path\" in str(e):\n        # resolve storage dir from KB metadata and retry","preventionTips":["Always resolve the storage dir before OSS-provider client calls","Guard provider-specific code paths with pipeline.provider checks","Ensure ingestion completes before scheduling reads/deletes"],"tags":["pageindex","oss","storage","rag"],"backgroundTag":"missing-required-parameter","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}