{"record":{"id":"1c2a73efbf2c3cd9","repo":"odysseus-dev/odysseus","slug":"upload-failed-e","errorCode":null,"errorMessage":"Upload failed: {e}","messagePattern":"Upload failed: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"routes/document/document_routes.py","lineNumber":266,"sourceCode":"        # doc (the doc creators below already handle a missing session).\n        if session_id:\n            db = SessionLocal()\n            try:\n                _get_session_or_404(db, session_id, user)\n            finally:\n                db.close()\n\n        if upload_handler is None:\n            raise HTTPException(500, \"Upload handler not configured\")\n\n        client_ip = request.client.host if request.client else \"unknown\"\n        try:\n            meta = upload_handler.save_upload(file, client_ip, owner=user)\n        except HTTPException:\n            raise\n        except Exception as e:\n            logger.error(f\"PDF import save_upload failed: {e}\")\n            raise HTTPException(500, f\"Upload failed: {e}\")\n\n        upload_id = meta[\"id\"]\n        pdf_path = _locate_current_user_upload(request, upload_id, user)\n        if not pdf_path:\n            raise HTTPException(500, \"Saved PDF could not be located\")\n\n        title = os.path.splitext(meta.get(\"original_name\") or meta.get(\"name\") or upload_id)[0]\n        try:\n            body_text = strip_pdf_content_marker(_process_pdf(pdf_path, owner=user))\n        except Exception:\n            body_text = None\n\n        is_form = False\n        try:\n            is_form = has_form_fields(pdf_path)\n        except Exception as e:\n            logger.warning(f\"has_form_fields failed for {pdf_path}: {e}\")\n","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/odysseus-dev/odysseus/blob/f9235ebbf13f693a6fd29ce70b097f6ec83705bf/routes/document/document_routes.py#L248-L284","documentation":"500 wrapper raised by POST /api/documents/import-pdf when upload_handler.save_upload(file, client_ip, owner=user) throws an unexpected exception (HTTPException from inside save_upload is passed through unchanged). save_upload is responsible for writing the multipart file to disk, so failures are almost always I/O or storage related; the original exception text follows 'Upload failed:'.","triggerScenarios":"Upload directory does not exist or is not writable by the API process; disk full; the uploaded file exceeds a size cap enforced inside save_upload with a non-HTTP exception; filename encoding problems producing an OSError on write.","commonSituations":"Containerized deployment where the uploads volume is missing or owned by root; disk quota exhausted on a long-running dev box; SELinux/AppArmor denying writes; very large PDFs hitting an internal limit implemented as ValueError instead of HTTPException.","solutions":["Check the server log line 'PDF import save_upload failed: <e>' for the underlying OSError/exception.","Verify the upload directory exists and the service user has write permission (mkdir -p, chown, or fix the volume mount).","Confirm free disk space and quotas on the upload volume.","If the cause is an internal size/validation check thrown as a plain exception, convert it to HTTPException(413/400) inside save_upload so it propagates cleanly."],"exampleFix":"# before\n# upload dir never created; save_upload raises PermissionError -> 500 Upload failed\n# after\nUploadHandler(base_dir, upload_dir)  # ensure upload_dir is created at init:\n# os.makedirs(upload_dir, exist_ok=True) inside UploadHandler.__init__","handlingStrategy":"retry","validationCode":"async function safeImport(fd) {\n  // pre-flight: file present and non-empty\n  if (!fd.get('file')?.size) throw new Error('empty file');\n  return api.post('/api/documents/import-pdf', fd, { timeout: 120000 });\n}","typeGuard":null,"tryCatchPattern":"try { meta = await api.post('/api/documents/import-pdf', fd); }\ncatch (e) {\n  if (/Upload failed/.test(e.message)) {\n    if (isTransient(e)) await retryWithBackoff(() => api.post('/api/documents/import-pdf', fd), 3);\n    else notify('Upload failed: ' + e.message);\n  } else throw e;\n}","preventionTips":["Monitor free disk space and upload-dir writability with a healthcheck","Cap upload size client-side to avoid internal limit exceptions","Give the API process ownership of its uploads directory"],"tags":["upload","filesystem","io","http-500","pdf"],"backgroundTag":null,"analyzedSha":"f9235ebbf13f693a6fd29ce70b097f6ec83705bf","analyzedAt":"2026-08-14T21:47:48.359Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}