HKUDS/DeepTutor · error · RuntimeError

PageIndex submit_document returned no doc_id: {result!r}

Error message

PageIndex submit_document returned no doc_id: {result!r}

What it means

submit_document calls the PageIndex SDK with wait=True and expects a dict containing a doc_id. If the result isn't a dict or doc_id is empty/missing, ingestion can't proceed so a RuntimeError with the repr of the result is raised.

Source

Thrown at deeptutor/services/rag/pipelines/pageindex/client.py:135

            )
        )

    @classmethod
    def local_read(cls, storage_path: str | Path) -> "PageIndexClient":
        """Open an existing Local Library without resolving indexing credentials."""
        _, local_type = _sdk_types()
        return cls(local_type(storage_path=str(storage_path)))

    async def submit_document(self, file_path: str | Path, *, mode: str | None = None) -> str:
        result = await asyncio.to_thread(
            self.sdk_client.submit_document,
            str(file_path),
            mode=mode,
            wait=True,
        )
        doc_id = result.get("doc_id") if isinstance(result, dict) else None
        if not doc_id:
            raise RuntimeError(f"PageIndex submit_document returned no doc_id: {result!r}")
        return str(doc_id)

    async def delete_document(self, doc_id: str) -> bool:
        await asyncio.to_thread(self.sdk_client.delete_document, doc_id)
        return True


__all__ = [
    "PageIndexClient",
    "resolve_oss_sdk_config",
]

View on GitHub (pinned to 3e82f13042)

Solutions

Inspect the repr in the error to see what the server actually returned; if it's an error payload, address the server-side cause.
Update the pageindex SDK / OSS server to matched versions so submit_document returns {"doc_id": ...}.
Retry the submission once — transient server hiccups can produce empty results; if it persists, check OSS server logs.

Example fix

# before
doc_id = await client.submit_document(file_path)  # RuntimeError: no doc_id

# after
result = await client.sdk_client.upload_document(str(file_path), mode=mode, wait=True)
if not (isinstance(result, dict) and result.get("doc_id")):
    logger.error("unexpected PageIndex response: %r", result)
    raise RuntimeError(f"PageIndex submit_document returned no doc_id: {result!r}")

Defensive patterns

Strategy: retry

Validate before calling

result = await client.sdk_client.upload_document(str(f), mode=mode, wait=True)
assert isinstance(result, dict) and result.get("doc_id"), f"bad response: {result!r}"

Type guard

def is_valid_submit_result(result) -> bool:
    return isinstance(result, dict) and bool(result.get("doc_id"))

Try / catch

for attempt in range(2):
    try:
        return await client.submit_document(file_path)
    except RuntimeError as e:
        if "no doc_id" in str(e) and attempt == 0:
            await asyncio.sleep(2)
            continue
        raise

Prevention

Pin matched OSS server and SDK versions.
Log full SDK responses during ingestion debugging.
Health-check the PageIndex OSS service before batch ingest.
Validate response shape immediately rather than downstream.

When it happens

Trigger: Calling _ingest → submit_document where the PageIndex SDK returns None, an error payload without doc_id, an empty dict, or a non-dict (string/list) response.

Common situations: PageIndex OSS server version mismatch returning a differently-shaped response, server-side ingestion failure swallowed into a status payload, or transient API error bodies; also SDK upgrades that rename the id field.

Related errors

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