invoke-ai/InvokeAI · error · HTTPException

Unexpected error while clearing queue: {e}

Error message

Unexpected error while clearing queue: {e}

What it means

Catch-all 500 for the clear route: exceptions from session_queue.clear() (which deletes queued items, optionally scoped to a user) are wrapped as HTTP 500. HTTPExceptions pass through untouched, so this only fires for unexpected service/DB failures.

Source

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

)
def clear(
    current_user: CurrentUserOrDefault,
    queue_id: str = Path(description="The queue id to perform this operation on"),
) -> ClearResult:
    """Clears the queue. Admin users clear (and cancel) all items; non-admin users clear only their
    own items — other users' queued and running items are untouched."""
    try:
        # The service cancels every in-progress item in scope itself (there can be several
        # with multiple workers), so there is no per-item authorization to do here: a
        # non-admin's scope is exactly their own items. The previous single get_current()
        # check both 403'd users whose arbitrary selected row belonged to someone else and
        # let a scoped clear interrupt another user's running generation.
        user_id = None if current_user.is_admin else current_user.user_id
        return ApiDependencies.invoker.services.session_queue.clear(queue_id, user_id=user_id)
    except HTTPException:
        raise
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Unexpected error while clearing queue: {e}")


@session_queue_router.put(
    "/{queue_id}/prune",
    operation_id="prune",
    responses={
        200: {"model": PruneResult},
    },
)
def prune(
    current_user: CurrentUserOrDefault,
    queue_id: str = Path(description="The queue id to perform this operation on"),
) -> PruneResult:
    """Prunes all completed or errored queue items. Non-admin users can only prune their own items."""
    try:
        # Admin users can prune all items, non-admin users can only prune their own
        user_id = None if current_user.is_admin else current_user.user_id
        return ApiDependencies.invoker.services.session_queue.prune(queue_id, user_id=user_id)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Read the {e} detail and server traceback for the root cause.
2. Verify the DB is writable and not locked (stop backups/other processes holding the SQLite file).
3. Confirm queue_id is valid via GET status endpoint.
4. Retry after transient contention; run migrations after upgrades.

Example fix

// before
clear_all_ids = [42, 43]
// after: distinguish truly unexpected failures
resp = requests.put(f"{base}/api/v1/queue/{queue_id}/clear")
if resp.status_code == 500:
    logging.error("queue clear failed: %s", resp.json().get('detail'))
    raise SystemExit(1)

const s = await fetch(`${base}/api/v1/queue/${queueId}/status`);
if (!s.ok) throw new Error(`queue ${queueId} not available for clear`);

function isClearResult(v): v is { canceled: number } | { deleted: number } {
  return typeof v === 'object' && v !== null && ('canceled' in v || 'deleted' in v);
}

try {
  const r = await fetch(`${base}/api/v1/queue/${queueId}/clear`, { method: 'PUT' });
  if (!r.ok) {
    const detail = (await r.json()).detail ?? '';
    throw new Error(`clear failed: ${detail}`);
  }
} catch (e) {
  logger.error('queue clear error', e); // check DB locks/writability
}

When it happens

Trigger: PUT /api/v1/queue/{queue_id}/clear when the service call raises: DB failure, unknown queue, lock contention, or a bug in the clear implementation.

Common situations: Clearing a large queue causing long DB transactions/locks; SQLite file locked by another process (e.g., backup); queue_id typo; post-upgrade schema mismatch.

Related errors

• Unexpected error while canceling by batch id: {e}
• Unexpected error while canceling by destination: {e}
• Unexpected error while pruning queue: {e}
• Unexpected error while getting queue status: {e}
• Unexpected error while getting batch status: {e}

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