invoke-ai/InvokeAI · error · HTTPException

Error setting client state

Error message

Error setting client state

What it means

HTTP 500 raised by set_client_state when the client_state_persistence service's set_by_key throws while writing (current_user.user_id, key, value). The real error is logged server-side; the client only sees the generic 500 detail.

Source

Thrown at invokeai/app/api/routers/client_state.py:45

@client_state_router.post(
    "/{queue_id}/set_by_key",
    operation_id="set_client_state",
    response_model=str,
)
def set_client_state(
    current_user: CurrentUserOrDefault,
    queue_id: str = Path(description="The queue id (ignored, kept for backwards compatibility)"),
    key: str = Query(..., description="Key to set"),
    value: str = Body(..., description="Stringified value to set"),
) -> str:
    """Sets the client state for the current user (or system user if not authenticated)"""
    try:
        return ApiDependencies.invoker.services.client_state_persistence.set_by_key(current_user.user_id, key, value)
    except Exception as e:
        logging.error(f"Error setting client state: {e}")
        raise HTTPException(status_code=500, detail="Error setting client state")


@client_state_router.get(
    "/{queue_id}/get_keys_by_prefix",
    operation_id="get_client_state_keys_by_prefix",
    response_model=list[str],
)
def get_client_state_keys_by_prefix(
    current_user: CurrentUserOrDefault,
    queue_id: str = Path(description="The queue id (ignored, kept for backwards compatibility)"),
    prefix: str = Query(..., description="Prefix to filter keys by"),
) -> list[str]:
    """Gets client state keys matching a prefix for the current user"""
    try:
        return ApiDependencies.invoker.services.client_state_persistence.get_keys_by_prefix(
            current_user.user_id, prefix
        )
    except Exception as e:

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Check server logs for 'Error setting client state' and the root exception
2. Verify the database backend is writable and migrations are current (alembic upgrade head)
3. Retry the write; shrink the stored value if it may exceed size limits
4. Verify the InvokeAI instance points at the intended database in the config

Example fix

// before
await setClientState(queueId, 'gallery', bigPayload); // 500
// after
try {
  await setClientState(queueId, 'gallery', bigPayload);
} catch {
  await setClientState(queueId, 'gallery', compactPayload); // smaller fallback value
}

if (value == null) throw new Error('setClientState requires a value');
if (JSON.stringify(value).length > MAX_STATE_SIZE) throw new Error('Client state value too large');

const isClientStateWriteError = (e) =>
  e?.response?.status === 500 && e?.response?.data?.detail === 'Error setting client state';

try {
  await api.post(`/client_state/${queueId}/set_by_key`, { key, value });
} catch (e) {
  if (isClientStateWriteError(e)) await retryWithBackoff(() => api.post(`/client_state/${queueId}/set_by_key`, { key, value }));
  else throw e;
}

When it happens

Trigger: POST /client_state/{queue_id}/set_by_key where the DB write fails: table missing, disk full, connection lost, or value serialization fails.

Common situations: SQLite database locked by a long-running generation job; oversized value exceeding a column/text limit; read-only filesystem after an upgrade; missing migration for the client-state table.

Related errors

• Error getting client state
• Error getting client state keys
• Error deleting client state key
• Error setting recall parameter {param_key}
• Failed to add image to board

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