openai/openai-python · warning · RuntimeError

Giving up on waiting for file {id} to finish processing afte

Error message

Giving up on waiting for file {id} to finish processing after {max_wait_seconds} seconds.

What it means

Raised by wait_for_file_processing when the file has not reached a terminal status (processed/failed) within max_wait_seconds while polling files.retrieve. It is a client-side timeout guard so the helper does not loop forever on a stuck upload. The RuntimeError is generic; catch RuntimeError to handle it.

Source

Thrown at src/openai/lib/_files.py:29

def wait_for_file_processing(
    files: Files,
    id: str,
    *,
    poll_interval: float,
    max_wait_seconds: float,
) -> FileObject:
    """Poll a file using the caller's resource and sleep hooks."""
    TERMINAL_STATES = {"processed", "error", "deleted"}

    start = time.time()
    file = files.retrieve(id)
    while file.status not in TERMINAL_STATES:
        files._sleep(poll_interval)

        file = files.retrieve(id)
        if time.time() - start > max_wait_seconds:
            raise RuntimeError(
                f"Giving up on waiting for file {id} to finish processing after {max_wait_seconds} seconds."
            )

    return file


async def async_wait_for_file_processing(
    files: AsyncFiles,
    id: str,
    *,
    poll_interval: float,
    max_wait_seconds: float,
) -> FileObject:
    """Poll a file using the caller's async resource and sleep hooks."""
    TERMINAL_STATES = {"processed", "error", "deleted"}

    start = time.time()
    file = await files.retrieve(id)

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Increase max_wait_seconds when uploading large files
2. Verify the file id is correct with files.retrieve(id) and check .status manually
3. Catch RuntimeError and re-check status or retry the wait
4. If the file status is 'failed', inspect file.error instead of waiting longer

Example fix

// before
file = wait_for_files.processing(client.files, file_id)
// after
try:
    file = wait_for_files.processing(client.files, file_id, max_wait_seconds=1800)
except RuntimeError:
    file = client.files.retrieve(file_id)
    if file.status != "processed":
        raise

status = client.files.retrieve(file_id).status
if status == "failed":
    raise RuntimeError(f"file {file_id} failed processing")

try:
    file = wait_for_files.processing(client.files, file_id, max_wait_seconds=1800)
except RuntimeError:
    file = client.files.retrieve(file_id)
    if file.status != "processed":
        raise

When it happens

Trigger: Calling openai.lib._files.wait_for_file_processing(file.id) with a small max_wait_seconds, or when the file takes longer than the default (10 min) to process, e.g. large batch files or API slowdowns.

Common situations: Large files.csv/batch uploads that process slowly; CI with tight timeouts; passing max_wait_seconds in the wrong unit (ms vs s); API incidents slowing processing.

Related errors

• Expected a non-empty value for `run_id` but received {run_id
• Expected a non-empty value for `file_id` but received {file_
• Expected a non-empty value for `file_id` but received {file_
• Expected a non-empty value for `vector_store_id` but receive
• Expected a non-empty value for `file_id` but received {file_

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/2f4e844f9334943e. Report an issue: GitHub.