odysseus-dev/odysseus · error · HTTPException
instruction is required
Error message
instruction is required
What it means
Error "instruction is required" thrown in odysseus-dev/odysseus.
Source
Thrown at routes/document/document_routes.py:1257
async def ai_fill_annotations(doc_id: str, request: Request) -> Dict[str, Any]:
"""Ask a vision-capable LLM to locate fillable areas on a flat PDF and
propose annotation values for each, given a free-form user instruction.
Returns a list of annotations: [{page, x, y, w, h, value}] where x/y/w/h
are page-percentages (0–100) — same coordinate system as the freeform
annotations the frontend already renders.
"""
import base64
import json
import fitz
from src.pdf_form_doc import find_source_upload_id
from src.document_processor import _resolve_vl_model, _load_vl_settings
from src.llm_core import llm_call_async
body = await request.json() if request.headers.get("content-type", "").startswith("application/json") else {}
instruction = (body or {}).get("instruction", "").strip()
if not instruction:
raise HTTPException(400, "instruction is required")
user = get_current_user(request)
db = SessionLocal()
try:
doc = db.query(Document).filter(Document.id == doc_id).first()
if not doc:
raise HTTPException(404, "Document not found")
_verify_doc_owner(db, doc, user)
upload_id = find_source_upload_id(doc.current_content or "")
if not upload_id:
raise HTTPException(400, "Document is not linked to a source PDF")
pdf_path = _locate_current_user_upload(request, upload_id, user)
if not pdf_path:
raise HTTPException(404, "Source PDF not found")
finally:
db.close()
# Resolve VL model (admin-configured or auto-detected vision-capable)View on GitHub (pinned to f9235ebbf1)
Solutions
- Provide a non-empty instruction in the request body.
- Ensure the client sends the instruction field before calling this endpoint.
When it happens
Trigger: 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.
Common situations: See trigger scenarios.
AI-assisted analysis of odysseus-dev/odysseus@f9235ebbf1 (2026-08-14).
Data as JSON: /api/errors/e4518dbafb3360e2.
Report an issue: GitHub.