HKUDS/DeepTutor · error · RuntimeError

PageIndex OSS requires a resolved Local Library path

Error message

PageIndex OSS requires a resolved Local Library path

What it means

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.

Source

Thrown at deeptutor/services/rag/pipelines/pageindex/pipeline.py:81

        *,
        client: Optional[PageIndexClient] = None,
        config_provider=None,
        provider: str = storage.CLOUD_PROVIDER,
    ) -> None:
        self.logger = logging.getLogger(__name__)
        self.kb_base_dir = kb_base_dir or DEFAULT_KB_BASE_DIR
        self._client = client
        self._config_provider = config_provider or get_pageindex_config
        self.provider = (
            storage.OSS_PROVIDER if provider == storage.OSS_PROVIDER else storage.CLOUD_PROVIDER
        )

    def _get_client(self, storage_dir: Path | None = None) -> PageIndexClient:
        if self._client is not None:
            return self._client
        if self.provider == storage.OSS_PROVIDER:
            if storage_dir is None:
                raise RuntimeError("PageIndex OSS requires a resolved Local Library path")
            return PageIndexClient.local(storage.sdk_storage_path(storage_dir))
        return PageIndexClient.cloud(self._config_provider())

    def _processing_mode(self, kb_name: str) -> str | None:
        if self.provider != storage.OSS_PROVIDER:
            return None
        try:
            from deeptutor.services.config.knowledge_base_config import KnowledgeBaseConfigService

            mode = (
                str(
                    KnowledgeBaseConfigService.get_instance(
                        Path(self.kb_base_dir) / "kb_config.json"
                    )
                    .get_kb_config(kb_name)
                    .get("pageindex_mode")
                    or ""
                )

View on GitHub (pinned to 3e82f13042)

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

Example fix

# before
client = pipeline._get_client()  # RuntimeError for OSS
# after
client = pipeline._get_client(storage_dir=kb_storage_dir)

Defensive patterns

Strategy: validation

Validate before calling

storage_dir = resolve_storage_dir_for_read(kb_dir, None)
if storage_dir is None:
    raise ValueError("KB has no local library yet; ingest first")
client = pipeline._get_client(storage_dir)

Try / catch

try:
    client = pipeline._get_client(storage_dir)
except RuntimeError as e:
    if "Local Library path" in str(e):
        # resolve storage dir from KB metadata and retry

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/e546b793136cef69. Report an issue: GitHub.