{"record":{"id":"55f282bc2d88d07b","repo":"bytedance/deer-flow","slug":"failed-to-upload-file-filename-str-e","errorCode":null,"errorMessage":"Failed to upload {file.filename}: {str(e)}","messagePattern":"Failed to upload (.+?): (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"backend/app/gateway/routers/uploads.py","lineNumber":419,"sourceCode":"                else:\n                    # Conversion failed and wrote nothing, so release the claim;\n                    # holding it would rename a later same-stem upload against\n                    # a name nothing occupies.\n                    seen_filenames.discard(unique_md_name)\n\n            uploaded_files.append(file_info)\n\n        except HTTPException as e:\n            await run_file_io(_cleanup_uploaded_paths, written_paths)\n            raise e\n        except UnsafeUploadPathError as e:\n            logger.warning(\"Skipping upload with unsafe destination %s: %s\", file.filename, e)\n            skipped_files.append(safe_filename)\n            continue\n        except Exception as e:\n            logger.error(f\"Failed to upload {file.filename}: {e}\")\n            await run_file_io(_cleanup_uploaded_paths, written_paths)\n            raise HTTPException(status_code=500, detail=f\"Failed to upload {file.filename}: {str(e)}\")\n\n    # Uploaded files are created with 0o600 permissions (owner read/write only).\n    # In Docker sandbox deployments the gateway writes as root but the sandbox\n    # process runs as a non-root user (typically UID 1000).  Without group/other\n    # read bits the sandbox cannot access the files — whether the uploads\n    # directory is bind-mounted into the container or synced via\n    # sandbox.update_file.  Always add group/other read bits so every sandbox\n    # configuration can read the uploaded content.\n    await run_file_io(_make_uploaded_paths_sandbox_readable, written_paths)\n\n    if sync_to_sandbox:\n        for file_path, virtual_path in sandbox_sync_targets:\n            await run_file_io(_sync_upload_to_sandbox, sandbox, file_path, virtual_path)\n\n    message = f\"Successfully uploaded {len(uploaded_files)} file(s)\"\n    if skipped_files:\n        message += f\"; skipped {len(skipped_files)} unsafe file(s)\"\n","sourceCodeStart":401,"sourceCodeEnd":437,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/routers/uploads.py#L401-L437","documentation":"HTTP 500 raised when an unexpected (non-HTTP, non-UnsafeUploadPath) exception escapes while processing one file in a multi-file upload. The gateway cleans up all files already written in this request (written_paths) before failing, so the upload is atomic. The detail includes the original exception text for the offending file.","triggerScenarios":"Any per-file I/O or processing failure during the upload loop: disk full, permission denied writing to the uploads dir, failure in the auto-convert-documents step, or sandbox file-sync errors raised inside the loop.","commonSituations":"Gateway container out of disk or inode-exhausted; uploads volume mounted read-only or owned by the wrong user; document conversion subprocess missing its binary; a filesystem watchdog/AV scanner locking files mid-write.","solutions":["Read the {str(e)} portion of the detail and the gateway log line 'Failed to upload <filename>' — it names the actual cause (OSError, ENOSPC, EACCES, converter error).","Fix the underlying filesystem issue: free disk space, correct ownership/permissions on the thread uploads directory.","If the error comes from auto-convert, disable uploads.auto_convert_documents in config or install the required converter, then retry.","Retry the upload after fixing — cleanup already removed partial writes, so the thread is in a clean state."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch 500 from the upload endpoint; parse detail for the per-file cause; the gateway already cleaned partial writes, so after fixing the cause a plain retry is safe.","preventionTips":["Alert on gateway disk usage so ENOSPC never reaches uploads.","Verify ownership/permissions of the uploads volume in deployment checks.","Test the document-conversion toolchain when enabling auto-convert."],"tags":["upload","http-500","filesystem","cleanup"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}