VectifyAI/PageIndex · warning · UserWarning

Document "{os.path.basename(file_path)}" was stored as "{sto

Error message

Document "{os.path.basename(file_path)}" was stored as "{stored}".

What it means

After uploading, the client compares the API-returned stored document name with the local basename; if they differ it warns (not raises) that the server stored the document under a different name, typically because the API sanitized/renamed the file.

Source

Thrown at pageindex/client.py:587

                list_documents entries (both modes).
            wait (bool): Return only once the document is ready for use.
                Cloud: polls status until "completed" (raises on "failed" or
                after 30 minutes). Local: indexing is synchronous already, so
                this changes nothing. Leave False to submit many documents
                concurrently and poll afterwards.

        Returns:
            dict: {'doc_id': ..., 'name': ...}. 'name' is the stored document
                name: a taken name gains a numeric suffix (name_1..name_99)
                and a UserWarning is emitted. Older cloud servers omit 'name'.
        """
        result = self._api.submit_document(
            file_path=file_path, mode=mode,
            beta_headers=beta_headers, folder_id=folder_id, metadata=metadata,
        )
        stored = result.get("name")
        if stored and stored != os.path.basename(file_path):
            warnings.warn(
                f'Document "{os.path.basename(file_path)}" was stored as '
                f'"{stored}".',
                stacklevel=2,
            )
        if wait:
            self._wait_until_ready(result["doc_id"])
        return result

    def _wait_until_ready(self, doc_id: str, timeout: float = 1800.0) -> None:
        import requests
        interval = 2.0
        deadline = time.monotonic() + timeout
        poll_failures = 0
        while True:
            try:
                status = self.get_document(doc_id).get("status")
                poll_failures = 0
            except (PageIndexAPIError, requests.RequestException) as exc:

View on GitHub (pinned to afb5e11976)

Solutions

1. This is a warning, not a failure — check result['name'] if the stored name matters to your workflow
2. Rename the local file to plain ASCII before upload if you need identical naming
3. Track documents by the returned doc_id rather than by name

Example fix

# before
result = client.submit_document('Отчёт 2024.pdf', wait=True)
# after
import shutil
shutil.copy('Отчёт 2024.pdf', 'report_2024.pdf')
result = client.submit_document('report_2024.pdf', wait=True)

import os
name = os.path.basename(file_path)
if name != name.encode('ascii', 'ignore').decode() or '  ' in name:
    file_path = ascii_safe_copy(file_path)  # preempt server rename

import warnings
with warnings.catch_warnings(record=True) as w:
    result = client.submit_document(file_path, wait=True)
renames = [x for x in w if 'was stored as' in str(x.message)]
stored = result.get('name') or os.path.basename(file_path)

When it happens

Trigger: Calling submit_document with a file whose basename gets changed server-side: non-ASCII characters, spaces, duplicate names auto-suffixed, or characters the service strips/normalizes.

Common situations: Uploading files with unicode/emoji names, re-uploading a document that already exists (server dedupes with a suffix), or platform-specific filename normalization.

AI-assisted analysis of VectifyAI/PageIndex@afb5e11976 (2026-08-27). Data as JSON: /api/errors/7d671a5f4a4b823c. Report an issue: GitHub.