{"record":{"id":"2f4e844f9334943e","repo":"openai/openai-python","slug":"giving-up-on-waiting-for-file-id-to-finish-proce","errorCode":null,"errorMessage":"Giving up on waiting for file {id} to finish processing after {max_wait_seconds} seconds.","messagePattern":"Giving up on waiting for file (.+?) to finish processing after (.+?) seconds\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"warning","filePath":"src/openai/lib/_files.py","lineNumber":29,"sourceCode":"\ndef wait_for_file_processing(\n    files: Files,\n    id: str,\n    *,\n    poll_interval: float,\n    max_wait_seconds: float,\n) -> FileObject:\n    \"\"\"Poll a file using the caller's resource and sleep hooks.\"\"\"\n    TERMINAL_STATES = {\"processed\", \"error\", \"deleted\"}\n\n    start = time.time()\n    file = files.retrieve(id)\n    while file.status not in TERMINAL_STATES:\n        files._sleep(poll_interval)\n\n        file = files.retrieve(id)\n        if time.time() - start > max_wait_seconds:\n            raise RuntimeError(\n                f\"Giving up on waiting for file {id} to finish processing after {max_wait_seconds} seconds.\"\n            )\n\n    return file\n\n\nasync def async_wait_for_file_processing(\n    files: AsyncFiles,\n    id: str,\n    *,\n    poll_interval: float,\n    max_wait_seconds: float,\n) -> FileObject:\n    \"\"\"Poll a file using the caller's async resource and sleep hooks.\"\"\"\n    TERMINAL_STATES = {\"processed\", \"error\", \"deleted\"}\n\n    start = time.time()\n    file = await files.retrieve(id)","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/lib/_files.py#L11-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase max_wait_seconds when uploading large files","Verify the file id is correct with files.retrieve(id) and check .status manually","Catch RuntimeError and re-check status or retry the wait","If the file status is 'failed', inspect file.error instead of waiting longer"],"exampleFix":"// before\nfile = wait_for_files.processing(client.files, file_id)\n// after\ntry:\n    file = wait_for_files.processing(client.files, file_id, max_wait_seconds=1800)\nexcept RuntimeError:\n    file = client.files.retrieve(file_id)\n    if file.status != \"processed\":\n        raise","handlingStrategy":"retry","validationCode":"status = client.files.retrieve(file_id).status\nif status == \"failed\":\n    raise RuntimeError(f\"file {file_id} failed processing\")","typeGuard":null,"tryCatchPattern":"try:\n    file = wait_for_files.processing(client.files, file_id, max_wait_seconds=1800)\nexcept RuntimeError:\n    file = client.files.retrieve(file_id)\n    if file.status != \"processed\":\n        raise","preventionTips":["Scale max_wait_seconds with file size","Check file.status before waiting","Handle terminal 'failed' status separately from timeouts"],"tags":["files","timeout","polling","batch"],"backgroundTag":"polling-timeout","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}