Troubleshoot Uploads
Fix common issues with uploading files.
Add --verbose (or -v) before the command name to see the SDK's INFO and DEBUG logs. It's a global option, so it must come before the command, not after.
Files Uploaded But Don't Appear
Ingestion lags the upload. Check the session status:
haystack-enterprise list-upload-sessions
haystack-enterprise get-upload-session <session-id>
An upload session left open expires after 24 hours, and files only start ingesting when it closes.
Some Files Were Skipped
By default, upload sends every supported type and skips unsupported types instead of failing the run. If you passed --use-type, only those types are uploaded. For details, see Supported File Types.
Duplicates in the Workspace
The default write mode is KEEP, which uploads a same-named file alongside the existing one. Use --write-mode OVERWRITE to replace instead.
Uploads Fail Behind a Corporate Proxy
If your network sends outbound traffic through a proxy, set the standard proxy environment variables before you run the upload: HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY. Use NO_PROXY for hosts that should connect directly. The SDK sends both its API calls and the file uploads to storage through the proxy. If the proxy URL contains a user name and password, the SDK uses them to authenticate with the proxy.
To check which route the SDK uses for file uploads, run the upload with --verbose and look for the log line that shows the upload host and the proxy, or direct if no proxy applies.
On Python 3.10, uploads can't reach storage through a proxy whose URL starts with https://. Use Python 3.11 or later, or a proxy with an http:// URL.
Upload Never Finishes or Times Out
With a blocking upload of many files, the SDK waits until the platform has ingested every file that reached storage. Files that fail to upload are never ingested, so the SDK doesn't wait for them. If an upload still doesn't finish, check the session status as described in Files Uploaded But Don't Appear. Files that were uploaded but failed during ingestion are shown in the session details, not in the upload summary.
Check Why a File Failed to Upload
When you upload with Python, the SDK reports every file that failed to upload as a FailedToUploadFileException, no matter how the file was sent. The original error, for example an HTTP or connection error, is available as the exception's __cause__. If your code checks the type of a failed file's exception, check exception.__cause__ instead. You can import FailedToUploadFileException from haystack_enterprise_sdk.
Related Information
Was this page helpful?