{"record":{"id":"58740c86476ff2d2","repo":"HKUDS/DeepTutor","slug":"str-exc","errorCode":null,"errorMessage":"str(exc)","messagePattern":"str\\(exc\\)","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"deeptutor/api/routers/book.py","lineNumber":539,"sourceCode":"    \"\"\"Stage 1: capture inputs + run IdeationAgent.\"\"\"\n    if not req.user_intent.strip():\n        raise HTTPException(status_code=400, detail=\"user_intent is required\")\n    engine = get_book_engine()\n    try:\n        book, proposal = await engine.create_book(\n            user_intent=req.user_intent,\n            chat_session_id=req.chat_session_id,\n            chat_selections=req.chat_selections,\n            notebook_refs=req.notebook_refs,\n            knowledge_bases=req.knowledge_bases,\n            question_categories=req.question_categories,\n            question_entries=req.question_entries,\n            language=req.language,\n            depth=req.depth,\n        )\n    except Exception as exc:  # noqa: BLE001\n        logger.error(f\"create_book failed: {exc}\", exc_info=True)\n        raise HTTPException(status_code=500, detail=str(exc))\n    return {\n        \"book\": book.model_dump(mode=\"json\"),\n        \"proposal\": proposal.model_dump(mode=\"json\"),\n    }\n\n\n@router.post(\"/books/confirm-proposal\")\nasync def confirm_proposal(req: ConfirmProposalRequest) -> dict[str, Any]:\n    \"\"\"Stage 2: user confirms (and possibly edits) the proposal → SpineAgent.\"\"\"\n    engine = get_book_engine()\n    edited: BookProposal | None = None\n    if req.proposal:\n        try:\n            edited = BookProposal.model_validate(req.proposal)\n        except Exception as exc:\n            raise HTTPException(status_code=400, detail=f\"Invalid proposal: {exc}\")\n    try:\n        book, spine = await engine.confirm_proposal(book_id=req.book_id, edited_proposal=edited)","sourceCodeStart":521,"sourceCodeEnd":557,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/book.py#L521-L557","documentation":"Generic 500 raised by the create_book endpoint when BookEngine.create_book throws an unexpected (non-ValueError) exception. The raw exception string is echoed to the client and the full traceback is logged server-side. It is a catch-all, so the underlying cause can be anything from LLM provider failures to document parsing errors inside the engine.","triggerScenarios":"POST /api/books/create with a valid request schema where the engine fails downstream: unreachable LLM provider, missing API key, RAG/KB lookup failure, or a bug in proposal generation. Any exception other than ValueError from engine.create_book.","commonSituations":"Missing OPENAI/LLM API key in env, provider rate-limit or timeout during proposal generation, malformed source documents, or version mismatch between router and engine after a partial upgrade.","solutions":["Check server logs — logger.error(..., exc_info=True) prints the full traceback that explains the real cause","Verify LLM provider config (API key, base URL, model name) is set in data/user/settings or env","Re-run the request with a simpler topic to rule out content/parsing issues","If the traceback points inside deeptutor, file/report it with the stack trace instead of retrying blindly"],"exampleFix":"// before\nraise HTTPException(status_code=500, detail=str(exc))\n// after (safer detail)\nraise HTTPException(status_code=500, detail=\"Book creation failed; see server logs\") from exc","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  const res = await fetch('/books/create', {...});\n  if (res.status === 500) { const e = await res.json(); console.error(e.detail); /* check server logs */ }\n} catch (netErr) { /* transport error */ }","preventionTips":["Pre-flight check LLM provider config before starting a book flow","Wrap the whole create->confirm->compile pipeline so a 500 aborts cleanly and shows server log reference","Retry with backoff once for transient provider failures"],"tags":["fastapi","http-500","book-engine","catch-all"],"backgroundTag":"internal-server-error","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}