{"record":{"id":"1d5308286669a98a","repo":"odysseus-dev/odysseus","slug":"upload-handler-not-configured","errorCode":null,"errorMessage":"Upload handler not configured","messagePattern":"Upload handler not configured","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"critical","filePath":"routes/document/document_routes.py","lineNumber":257,"sourceCode":"        )\n        from src.document_processor import _process_pdf, strip_pdf_content_marker\n        import os\n\n        from src.auth_helpers import require_privilege\n        user = require_privilege(request, \"can_use_documents\")\n\n        # session_id is optional — a library import isn't tied to a chat. When\n        # given, validate it; otherwise the PDF becomes a session-less library\n        # 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))","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/odysseus-dev/odysseus/blob/f9235ebbf13f693a6fd29ce70b097f6ec83705bf/routes/document/document_routes.py#L239-L275","documentation":"Raised by POST /api/documents/import-pdf when the route factory was built without an upload handler (setup_document_routes(session_manager, upload_handler=None)). The handler is the component that persists uploaded files and returns metadata; without it the endpoint cannot save any PDF and fails fast with a 500 before touching the file.","triggerScenarios":"Calling setup_document_routes() without the upload_handler argument (it defaults to None), or a wiring/regression where the dependency-injection step that constructs UploadHandler was skipped during app startup.","commonSituations":"New deployment or test harness that mounts document routes directly instead of through the main app factory; refactor renamed the UploadHandler parameter and callers now pass None; running route unit tests without the upload fixture.","solutions":["Find where setup_document_routes is called and pass the app's UploadHandler instance as the second argument.","Import src.upload_handler.UploadHandler, construct it with the configured base/upload dir, and inject it during router setup.","Add a startup assertion or test that upload_handler is not None before serving, so misconfiguration fails at boot rather than at first PDF import."],"exampleFix":"# before\nrouter = setup_document_routes(session_manager)  # upload_handler defaults to None -> 500\n# after\nfrom src.upload_handler import UploadHandler\nrouter = setup_document_routes(session_manager, UploadHandler(base_dir, upload_dir))","handlingStrategy":"validation","validationCode":"// before mounting, assert the wiring\nimport { setup_document_routes } from './routes/document/document_routes';\nif (!uploadHandler) throw new Error('setup_document_routes requires an UploadHandler');\napp.use(setup_document_routes(sessionManager, uploadHandler));","typeGuard":"def has_upload_handler(router_factory_kwargs: dict) -> bool:\n    return router_factory_kwargs.get('upload_handler') is not None","tryCatchPattern":"try { await api.post('/api/documents/import-pdf', fd); }\ncatch (e) { if (e.message.includes('Upload handler not configured')) { /* config bug, file an alert, do not retry */ } throw e; }","preventionTips":["Fail fast at startup if upload_handler is None","Add a boot-time smoke test that hits import-pdf in a test environment","Treat this error as a deployment blocker, never a runtime condition"],"tags":["fastapi","configuration","dependency-injection","http-500"],"backgroundTag":null,"analyzedSha":"f9235ebbf13f693a6fd29ce70b097f6ec83705bf","analyzedAt":"2026-08-14T21:47:48.359Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}