invoke-ai/InvokeAI · error · HTTPException

Unexpected error while enqueuing batch: {e}

Error message

Unexpected error while enqueuing batch: {e}

What it means

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.

Source

Thrown at invokeai/app/api/routers/session_queue.py:141

    responses={
        201: {"model": EnqueueBatchResult},
    },
)
async def enqueue_batch(
    current_user: CurrentUserOrDefault,
    queue_id: str = Path(description="The queue id to perform this operation on"),
    batch: Batch = Body(description="Batch to process"),
    prepend: bool = Body(default=False, description="Whether or not to prepend this batch in the queue"),
) -> EnqueueBatchResult:
    """Processes a batch and enqueues the output graphs for execution for the current user."""
    await asyncio.to_thread(assert_image_move_maintenance_inactive)

    try:
        return await ApiDependencies.invoker.services.session_queue.enqueue_batch(
            queue_id=queue_id, batch=batch, prepend=prepend, user_id=current_user.user_id
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Unexpected error while enqueuing batch: {e}")


@session_queue_router.get(
    "/{queue_id}/list_all",
    operation_id="list_all_queue_items",
    responses={
        200: {"model": list[SessionQueueItem]},
    },
)
def list_all_queue_items(
    current_user: CurrentUserOrDefault,
    queue_id: str = Path(description="The queue id to perform this operation on"),
    destination: Optional[str] = Query(default=None, description="The destination of queue items to fetch"),
) -> list[SessionQueueItem]:
    """Gets all queue items"""
    try:
        items = ApiDependencies.invoker.services.session_queue.list_all_queue_items(
            queue_id=queue_id,

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Read detail from the response - it embeds the underlying exception message; fix the specific cause it names
2. Verify queue_id exists (GET the queue) before enqueueing
3. Validate the batch payload (graph, batch size, params) matches the current API schema
4. Check database health (file writable, not locked) and retry the enqueue

Example fix

// before
curl -X POST /api/v1/queue/default/enqueue_batch -d '{...}'  # -> 500
// after: ensure queue exists first
await fetch(`/api/v1/queue/${queueId}`) // 404? create/get the queue before enqueueing
await fetch(`/api/v1/queue/${queueId}/enqueue_batch`, {method: 'POST', body})

const q = await fetch(`/api/v1/queue/${queueId}`);
if (!q.ok) throw new Error(`Queue ${queueId} does not exist; create it before enqueueing`);
JSON.stringify(batch); // throws on malformed payload before the request

function isBatchValid(b) { return !!b && typeof b === 'object' && Array.isArray(b.queue_ids ?? b.items ?? []) && Object.keys(b).length > 0; }

try {
  const res = await fetch(`/api/v1/queue/${queueId}/enqueue_batch`, {method:'POST', headers:{'Content-Type':'application/json'}, body: JSON.stringify(batch)});
  if (res.status === 500) { const {detail} = await res.json(); throw new Error(detail); }
} catch (e) {
  console.error('enqueue failed:', e.message); // detail embeds the underlying cause
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unexpected error while listing all queue items: {e}
• Unexpected error while listing all queue item ids: {e}
• Failed to get queue items
• Failed to get queue item summaries
• Unexpected error while resuming queue: {e}

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/869b2f68803b12a9. Report an issue: GitHub.