{"record":{"id":"869b2f68803b12a9","repo":"invoke-ai/InvokeAI","slug":"unexpected-error-while-enqueuing-batch-e","errorCode":null,"errorMessage":"Unexpected error while enqueuing batch: {e}","messagePattern":"Unexpected error while enqueuing batch: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"invokeai/app/api/routers/session_queue.py","lineNumber":141,"sourceCode":"    responses={\n        201: {\"model\": EnqueueBatchResult},\n    },\n)\nasync def enqueue_batch(\n    current_user: CurrentUserOrDefault,\n    queue_id: str = Path(description=\"The queue id to perform this operation on\"),\n    batch: Batch = Body(description=\"Batch to process\"),\n    prepend: bool = Body(default=False, description=\"Whether or not to prepend this batch in the queue\"),\n) -> EnqueueBatchResult:\n    \"\"\"Processes a batch and enqueues the output graphs for execution for the current user.\"\"\"\n    await asyncio.to_thread(assert_image_move_maintenance_inactive)\n\n    try:\n        return await ApiDependencies.invoker.services.session_queue.enqueue_batch(\n            queue_id=queue_id, batch=batch, prepend=prepend, user_id=current_user.user_id\n        )\n    except Exception as e:\n        raise HTTPException(status_code=500, detail=f\"Unexpected error while enqueuing batch: {e}\")\n\n\n@session_queue_router.get(\n    \"/{queue_id}/list_all\",\n    operation_id=\"list_all_queue_items\",\n    responses={\n        200: {\"model\": list[SessionQueueItem]},\n    },\n)\ndef list_all_queue_items(\n    current_user: CurrentUserOrDefault,\n    queue_id: str = Path(description=\"The queue id to perform this operation on\"),\n    destination: Optional[str] = Query(default=None, description=\"The destination of queue items to fetch\"),\n) -> list[SessionQueueItem]:\n    \"\"\"Gets all queue items\"\"\"\n    try:\n        items = ApiDependencies.invoker.services.session_queue.list_all_queue_items(\n            queue_id=queue_id,","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/api/routers/session_queue.py#L123-L159","documentation":"Thrown by the POST batch-enqueue endpoint in session_queue.py: any exception from SessionQueue.enqueue_batch (queue not found, validation, DB error) is converted into a 500 with the original message interpolated into the detail. It signals that the batch could not be enqueued for an unexpected (unclassified) reason rather than a known 4xx condition.","triggerScenarios":"POSTing a batch to /queue/{queue_id}/enqueue_batch where queue_id does not exist, the batch payload fails service-level validation, or the SQLite session-queue write fails.","commonSituations":"Client caching a stale queue_id after the queue was cleared/deleted; enqueueing while the DB file is locked or the disk is full; API client version sending a batch shape the current service rejects.","solutions":["Read detail from the response - it embeds the underlying exception message; fix the specific cause it names","Verify queue_id exists (GET the queue) before enqueueing","Validate the batch payload (graph, batch size, params) matches the current API schema","Check database health (file writable, not locked) and retry the enqueue"],"exampleFix":"// before\ncurl -X POST /api/v1/queue/default/enqueue_batch -d '{...}'  # -> 500\n// after: ensure queue exists first\nawait fetch(`/api/v1/queue/${queueId}`) // 404? create/get the queue before enqueueing\nawait fetch(`/api/v1/queue/${queueId}/enqueue_batch`, {method: 'POST', body})","handlingStrategy":"try-catch","validationCode":"const q = await fetch(`/api/v1/queue/${queueId}`);\nif (!q.ok) throw new Error(`Queue ${queueId} does not exist; create it before enqueueing`);\nJSON.stringify(batch); // throws on malformed payload before the request","typeGuard":"function isBatchValid(b) { return !!b && typeof b === 'object' && Array.isArray(b.queue_ids ?? b.items ?? []) && Object.keys(b).length > 0; }","tryCatchPattern":"try {\n  const res = await fetch(`/api/v1/queue/${queueId}/enqueue_batch`, {method:'POST', headers:{'Content-Type':'application/json'}, body: JSON.stringify(batch)});\n  if (res.status === 500) { const {detail} = await res.json(); throw new Error(detail); }\n} catch (e) {\n  console.error('enqueue failed:', e.message); // detail embeds the underlying cause\n}","preventionTips":["Verify queue_id exists immediately before enqueueing","Validate batch payloads against the current OpenAPI schema","Keep client and server InvokeAI versions in sync","Retry once on transient failures, then surface the embedded cause"],"tags":["fastapi","http-500","queue","api"],"backgroundTag":"api-internal-server-error","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}