{"record":{"id":"1c975f2abd807790","repo":"opendatalab/MinerU","slug":"failed-to-load-file-upload-original-name-exc","errorCode":null,"errorMessage":"Failed to load file {upload.original_name}: {exc}","messagePattern":"Failed to load file (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"mineru/cli/fast_api.py","lineNumber":816,"sourceCode":"            StoredUpload(\n                original_name=upload.original_name,\n                stem=effective_stem,\n                path=upload.path,\n            )\n            for upload, effective_stem in zip(uploads, normalized_stems)\n        ]\n    return uploads\n\n\ndef load_parse_inputs(uploads: list[StoredUpload]) -> tuple[list[str], list[bytes]]:\n    pdf_file_names = []\n    pdf_bytes_list = []\n\n    for upload in uploads:\n        try:\n            pdf_bytes = read_fn(Path(upload.path))\n        except Exception as exc:\n            raise RuntimeError(f\"Failed to load file {upload.original_name}: {exc}\") from exc\n        pdf_file_names.append(upload.stem)\n        pdf_bytes_list.append(pdf_bytes)\n    return pdf_file_names, pdf_bytes_list\n\n\nasync def run_parse_job(\n    output_dir: str,\n    uploads: list[StoredUpload],\n    request_options: ParseRequestOptions | AsyncParseTask,\n    config: dict[str, Any],\n) -> list[str]:\n    pdf_file_names, pdf_bytes_list = await asyncio.to_thread(load_parse_inputs, uploads)\n    actual_lang_list = normalize_lang_list(request_options.lang_list, len(pdf_file_names))\n    response_file_names = list(pdf_file_names)\n\n    parse_kwargs = dict(\n        output_dir=output_dir,\n        pdf_file_names=list(pdf_file_names),","sourceCodeStart":798,"sourceCodeEnd":834,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/cli/fast_api.py#L798-L834","documentation":"RuntimeError raised by load_parse_inputs in fast_api.py when read_fn(Path(upload.path)) throws while loading an already-stored upload from disk, just before parsing starts (run in a worker thread via asyncio.to_thread). The original exception is chained (__cause__). It means the file passed upload-time validation but could not be read afterwards: deleted by the retention/cleanup sweeper, moved, permission problems, or a full/corrupted disk.","triggerScenarios":"The task sat in the queue long enough that the background cleanup deleted the upload before a worker read it; two requests racing where one cleanup removes the temp file; the upload directory is on ephemeral storage (container restart, tmpfs clear); OS-level permission change on the uploads dir between upload and parse.","commonSituations":"Long queues under load with aggressive task retention settings; deployments where the API's upload dir is not persistent; security software quarantining files; disk-full events truncating written files.","solutions":["Look at the chained __cause__ in the traceback — it names the real IOError reason (missing file vs permission vs I/O error).","Check that the upload directory is writable and persistent for the API process for the whole task lifetime; move it off tmpfs if containers restart.","Make task/file retention (MINERU_API_TASK_RETENTION_SECONDS and related cleanup intervals) longer than your worst-case queue wait so files are not swept early.","Retry the request: if it was a transient cleanup race or disk blip, a fresh upload succeeds."],"exampleFix":"# before\ntask = requests.post(f'{base}/file_parse', files=files).json()\n# ...later, task fails with 'Failed to load file report.pdf: [Errno 2] No such file or directory'\n\n# after (client-side guard)\nresp = requests.post(f'{base}/file_parse', files=files)\nif resp.status_code >= 500:\n    resp = requests.post(f'{base}/file_parse', files=files)  # retry once on load failure","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"resp = submit(files)\nif task_failed_with(resp, 'Failed to load file'):\n    resp = submit(files)  # one retry: transient cleanup race / disk blip","preventionTips":["Keep upload directories on persistent, writable storage owned by the API user.","Make retention/cleanup windows strictly longer than maximum queue wait times.","Monitor disk space and upload-dir inode usage where the API writes."],"tags":["mineru","fastapi","file-io","race-condition","cleanup"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}