{"record":{"id":"7d671a5f4a4b823c","repo":"VectifyAI/PageIndex","slug":"document-os-path-basename-file-path-was-store","errorCode":null,"errorMessage":"Document \"{os.path.basename(file_path)}\" was stored as \"{stored}\".","messagePattern":"Document \"(.+?)\" was stored as \"(.+?)\"\\.","errorType":"console","errorClass":"UserWarning","httpStatus":null,"severity":"warning","filePath":"pageindex/client.py","lineNumber":587,"sourceCode":"                list_documents entries (both modes).\n            wait (bool): Return only once the document is ready for use.\n                Cloud: polls status until \"completed\" (raises on \"failed\" or\n                after 30 minutes). Local: indexing is synchronous already, so\n                this changes nothing. Leave False to submit many documents\n                concurrently and poll afterwards.\n\n        Returns:\n            dict: {'doc_id': ..., 'name': ...}. 'name' is the stored document\n                name: a taken name gains a numeric suffix (name_1..name_99)\n                and a UserWarning is emitted. Older cloud servers omit 'name'.\n        \"\"\"\n        result = self._api.submit_document(\n            file_path=file_path, mode=mode,\n            beta_headers=beta_headers, folder_id=folder_id, metadata=metadata,\n        )\n        stored = result.get(\"name\")\n        if stored and stored != os.path.basename(file_path):\n            warnings.warn(\n                f'Document \"{os.path.basename(file_path)}\" was stored as '\n                f'\"{stored}\".',\n                stacklevel=2,\n            )\n        if wait:\n            self._wait_until_ready(result[\"doc_id\"])\n        return result\n\n    def _wait_until_ready(self, doc_id: str, timeout: float = 1800.0) -> None:\n        import requests\n        interval = 2.0\n        deadline = time.monotonic() + timeout\n        poll_failures = 0\n        while True:\n            try:\n                status = self.get_document(doc_id).get(\"status\")\n                poll_failures = 0\n            except (PageIndexAPIError, requests.RequestException) as exc:","sourceCodeStart":569,"sourceCodeEnd":605,"githubUrl":"https://github.com/VectifyAI/PageIndex/blob/afb5e119766630af6014b04fe8b53357527bc05e/pageindex/client.py#L569-L605","documentation":"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.","triggerScenarios":"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.","commonSituations":"Uploading files with unicode/emoji names, re-uploading a document that already exists (server dedupes with a suffix), or platform-specific filename normalization.","solutions":["This is a warning, not a failure — check result['name'] if the stored name matters to your workflow","Rename the local file to plain ASCII before upload if you need identical naming","Track documents by the returned doc_id rather than by name"],"exampleFix":"# before\nresult = client.submit_document('Отчёт 2024.pdf', wait=True)\n# after\nimport shutil\nshutil.copy('Отчёт 2024.pdf', 'report_2024.pdf')\nresult = client.submit_document('report_2024.pdf', wait=True)","handlingStrategy":"fallback","validationCode":"import os\nname = os.path.basename(file_path)\nif name != name.encode('ascii', 'ignore').decode() or '  ' in name:\n    file_path = ascii_safe_copy(file_path)  # preempt server rename","typeGuard":null,"tryCatchPattern":"import warnings\nwith warnings.catch_warnings(record=True) as w:\n    result = client.submit_document(file_path, wait=True)\nrenames = [x for x in w if 'was stored as' in str(x.message)]\nstored = result.get('name') or os.path.basename(file_path)","preventionTips":["Track documents by doc_id, never by name","Normalize filenames to plain ASCII before upload","Assert name uniqueness server-side if you rely on names as keys"],"tags":["upload","filename","warning","rename"],"backgroundTag":"server-side-filename-mismatch","analyzedSha":"afb5e119766630af6014b04fe8b53357527bc05e","analyzedAt":"2026-08-27T11:20:48.519Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}