{"record":{"id":"e4518dbafb3360e2","repo":"odysseus-dev/odysseus","slug":"instruction-is-required","errorCode":null,"errorMessage":"instruction is required","messagePattern":"instruction is required","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"routes/document/document_routes.py","lineNumber":1257,"sourceCode":"    async def ai_fill_annotations(doc_id: str, request: Request) -> Dict[str, Any]:\n        \"\"\"Ask a vision-capable LLM to locate fillable areas on a flat PDF and\n        propose annotation values for each, given a free-form user instruction.\n\n        Returns a list of annotations: [{page, x, y, w, h, value}] where x/y/w/h\n        are page-percentages (0–100) — same coordinate system as the freeform\n        annotations the frontend already renders.\n        \"\"\"\n        import base64\n        import json\n        import fitz\n        from src.pdf_form_doc import find_source_upload_id\n        from src.document_processor import _resolve_vl_model, _load_vl_settings\n        from src.llm_core import llm_call_async\n\n        body = await request.json() if request.headers.get(\"content-type\", \"\").startswith(\"application/json\") else {}\n        instruction = (body or {}).get(\"instruction\", \"\").strip()\n        if not instruction:\n            raise HTTPException(400, \"instruction is required\")\n\n        user = get_current_user(request)\n        db = SessionLocal()\n        try:\n            doc = db.query(Document).filter(Document.id == doc_id).first()\n            if not doc:\n                raise HTTPException(404, \"Document not found\")\n            _verify_doc_owner(db, doc, user)\n            upload_id = find_source_upload_id(doc.current_content or \"\")\n            if not upload_id:\n                raise HTTPException(400, \"Document is not linked to a source PDF\")\n            pdf_path = _locate_current_user_upload(request, upload_id, user)\n            if not pdf_path:\n                raise HTTPException(404, \"Source PDF not found\")\n        finally:\n            db.close()\n\n        # Resolve VL model (admin-configured or auto-detected vision-capable)","sourceCodeStart":1239,"sourceCodeEnd":1275,"githubUrl":"https://github.com/odysseus-dev/odysseus/blob/f9235ebbf13f693a6fd29ce70b097f6ec83705bf/routes/document/document_routes.py#L1239-L1275","documentation":"Error \"instruction is required\" thrown in odysseus-dev/odysseus.","triggerScenarios":"Triggered when the corresponding server-side validation or runtime check at the recorded location rejects the request or operation and returns this error message to the caller.","commonSituations":"See trigger scenarios.","solutions":["Provide a non-empty instruction in the request body.","Ensure the client sends the instruction field before calling this endpoint."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"f9235ebbf13f693a6fd29ce70b097f6ec83705bf","analyzedAt":"2026-08-14T21:47:48.359Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}