feat(chat): delete never-used chat sessions when a send fails during setup

The send flow commits the user message partway through setup; a failure
before that commit (LLM misconfig, cost limit, permission or hook
rejection) leaves the pre-created session with only its SYSTEM root —
no user-visible content. Best-effort hard-delete such sessions from the
failure paths of _stream_chat_turn, guarded by a no-non-SYSTEM-messages
check so a failure after the user message landed never touches a real
conversation, and never masking the original error.

This prevents most "unnamed husk" sidebar rows at the source; sends
that never reach the backend at all are left to the background
failed-chat cleanup.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jmelahman

backend/onyx/chat/process_message.py

@@ -81,6 +81,7 @@
 from onyx.context.search.models import BaseFilters, SearchDoc
 from onyx.db.chat import (
     create_new_chat_message,
+    delete_chat_session_if_never_used,
     get_chat_session_by_id,
     get_or_create_root_message,
     reserve_message_id,
@@ -1633,6 +1634,30 @@ def _read_stream() -> AnswerStream:
     return _read_stream()
 
 
+def _cleanup_failed_chat_session(chat_session_id: UUID | None) -> None:
+    """Best-effort: hard-delete the session a failed send left with no
+    user-visible content, so it doesn't linger as an unnamed husk until the
+    background failed-chat cleanup reclaims it. A failure after the user
+    message was committed is a real conversation and is left untouched.
+    Never raises — the original error must propagate unmasked.
+    """
+    if chat_session_id is None:
+        return
+    try:
+        with get_session_with_current_tenant() as db_session:
+            if delete_chat_session_if_never_used(
+                chat_session_id=chat_session_id, db_session=db_session
+            ):
+                logger.info(
+                    "Deleted never-used chat session %s after failed send",
+                    chat_session_id,
+                )
+    except Exception:
+        logger.exception(
+            "Cleanup of never-used chat session %s failed", chat_session_id
+        )
+
+
 def _stream_chat_turn(
     new_msg_req: SendMessageRequest,
     user: User,
@@ -1688,6 +1713,19 @@ def _stream_chat_turn(
     pre_run_packets: list[AnswerStreamPart] = []
     run_started = False
 
+    def _failed_chat_session_id() -> UUID | None:
+        """The session this failed send targeted: known from setup once built,
+        else from the request, else from the CreateChatSessionID packet when
+        the send created the session itself."""
+        if setup is not None:
+            return setup.chat_session.id
+        if new_msg_req.chat_session_id:
+            return new_msg_req.chat_session_id
+        for packet in pre_run_packets:
+            if isinstance(packet, CreateChatSessionID):
+                return packet.chat_session_id
+        return None
+
     try:
         with get_session_with_current_tenant() as setup_db_session:
             try:
@@ -1791,6 +1829,7 @@ def _stream_chat_turn(
     except OnyxError as e:
         if e.error_code is not OnyxErrorCode.QUERY_REJECTED:
             log_onyx_error(e)
+        _cleanup_failed_chat_session(_failed_chat_session_id())
         yield StreamingError(
             error=e.detail,
             error_code=e.error_code.code,
@@ -1800,6 +1839,7 @@ def _stream_chat_turn(
 
     except ValueError as e:
         logger.exception("Failed to process chat message.")
+        _cleanup_failed_chat_session(_failed_chat_session_id())
         yield StreamingError(
             error=str(e),
             error_code="VALIDATION_ERROR",
@@ -1833,6 +1873,10 @@ def _stream_chat_turn(
     except Exception as e:
         logger.exception("Failed to process chat message due to %s", e)
         stack_trace = traceback.format_exc()
+        # No-ops when the user message was already committed (the LLM only runs
+        # after it), so this only fires for setup failures. Same applies to the
+        # handlers above; EmptyLLMResponseError is post-commit by construction.
+        _cleanup_failed_chat_session(_failed_chat_session_id())
 
         llm = setup.llms[0] if setup else None
         if llm:

backend/onyx/db/chat.py

@@ -450,6 +450,42 @@ def get_chat_sessions_older_than(
     return returned_sessions
 
 
+def delete_chat_session_if_never_used(
+    chat_session_id: UUID,
+    db_session: Session,
+) -> bool:
+    """Hard-delete a chat session iff it has never contained a non-SYSTEM
+    message, i.e. holds no user-visible content.
+
+    Used best-effort by the send-message failure path: a failure before the
+    user message was committed would otherwise leave an unnamed husk session
+    behind. Returns True if the session was deleted.
+    """
+    session_exists = db_session.execute(
+        select(ChatSession.id).where(ChatSession.id == chat_session_id)
+    ).scalar_one_or_none()
+    if session_exists is None:
+        return False
+
+    has_user_visible_message = db_session.execute(
+        select(ChatMessage.id)
+        .where(ChatMessage.chat_session_id == chat_session_id)
+        .where(ChatMessage.message_type != MessageType.SYSTEM)
+        .limit(1)
+    ).scalar_one_or_none()
+    if has_user_visible_message is not None:
+        return False
+
+    delete_chat_session(
+        user_id=None,
+        chat_session_id=chat_session_id,
+        db_session=db_session,
+        include_deleted=True,
+        hard_delete=True,
+    )
+    return True
+
+
 def get_chat_message(
     chat_message_id: int,
     user_id: UUID | None,

backend/tests/external_dependency_unit/chat/test_failed_send_session_cleanup.py

@@ -0,0 +1,163 @@
+"""Tests for husk prevention in the send-message failure path.
+
+A send that fails before the user message is committed leaves a session with
+no user-visible content; the failure path is expected to delete it so it never
+shows up as an unnamed husk in the sidebar. A failure after the user message
+landed is a real conversation and must survive.
+"""
+
+import uuid
+from collections.abc import Generator
+from unittest.mock import patch
+from uuid import UUID
+
+import pytest
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from onyx.chat.models import AnswerStreamPart, StreamingError
+from onyx.chat.process_message import handle_stream_message_objects
+from onyx.configs.constants import MessageType
+from onyx.db.chat import create_chat_session, delete_chat_session
+from onyx.db.models import ChatMessage, ChatSession, Persona, User
+from onyx.db.persona import upsert_persona
+from onyx.server.query_and_chat.models import SendMessageRequest
+from tests.external_dependency_unit.answer.conftest import ensure_default_llm_provider
+from tests.external_dependency_unit.conftest import create_test_user
+
+
+@pytest.fixture
+def test_user(db_session: Session) -> User:
+    return create_test_user(db_session, email_prefix="failed_send_cleanup")
+
+
+@pytest.fixture
+def test_persona(db_session: Session) -> Persona:
+    ensure_default_llm_provider(db_session)
+    return upsert_persona(
+        user=None,
+        name=f"Failed Send Cleanup Persona {uuid.uuid4()}",
+        description="Tool-less persona for send-failure tests",
+        starter_messages=None,
+        system_prompt=None,
+        task_prompt=None,
+        datetime_aware=None,
+        is_public=True,
+        db_session=db_session,
+        tool_ids=[],
+        document_set_ids=None,
+        is_listed=True,
+        default_model_configuration_id=None,
+    )
+
+
+def _session_row_exists(db_session: Session, chat_session_id: UUID) -> bool:
+    # Plain SELECT on purpose: Session.get() on an identity-map instance whose
+    # row was deleted by another session raises ObjectDeletedError on refresh.
+    return (
+        db_session.execute(
+            select(ChatSession.id).where(ChatSession.id == chat_session_id)
+        ).first()
+        is not None
+    )
+
+
+@pytest.fixture
+def session_tracker(db_session: Session) -> Generator[list[UUID], None, None]:
+    created: list[UUID] = []
+    yield created
+    db_session.expunge_all()
+    for session_id in created:
+        if _session_row_exists(db_session, session_id):
+            delete_chat_session(
+                user_id=None,
+                chat_session_id=session_id,
+                db_session=db_session,
+                include_deleted=True,
+                hard_delete=True,
+            )
+
+
+def _consume_stream_expecting_error(
+    new_msg_req: SendMessageRequest, user: User
+) -> None:
+    packets: list[AnswerStreamPart] = list(
+        handle_stream_message_objects(new_msg_req=new_msg_req, user=user)
+    )
+    assert any(isinstance(packet, StreamingError) for packet in packets)
+
+
+def test_failure_before_user_message_commit_deletes_session(
+    db_session: Session,
+    test_user: User,
+    test_persona: Persona,
+    session_tracker: list[UUID],
+) -> None:
+    chat_session = create_chat_session(
+        db_session=db_session,
+        description=None,
+        user_id=test_user.id,
+        persona_id=test_persona.id,
+    )
+    session_tracker.append(chat_session.id)
+    # Release this session's snapshot so we observe the flow's own commits.
+    db_session.commit()
+
+    # verify_user_files runs during setup, before the user message is written.
+    with patch(
+        "onyx.chat.process_message.verify_user_files",
+        side_effect=RuntimeError("forced setup failure"),
+    ):
+        _consume_stream_expecting_error(
+            SendMessageRequest(message="hello", chat_session_id=chat_session.id),
+            test_user,
+        )
+
+    db_session.expunge_all()
+    assert not _session_row_exists(db_session, chat_session.id)
+    assert (
+        db_session.execute(
+            select(ChatMessage.id).where(ChatMessage.chat_session_id == chat_session.id)
+        ).first()
+        is None
+    )
+
+
+def test_failure_after_user_message_commit_keeps_session(
+    db_session: Session,
+    test_user: User,
+    test_persona: Persona,
+    session_tracker: list[UUID],
+) -> None:
+    chat_session = create_chat_session(
+        db_session=db_session,
+        description=None,
+        user_id=test_user.id,
+        persona_id=test_persona.id,
+    )
+    session_tracker.append(chat_session.id)
+    db_session.commit()
+
+    # reserve_message_id runs right after the user message is committed.
+    with patch(
+        "onyx.chat.process_message.reserve_message_id",
+        side_effect=RuntimeError("forced post-commit failure"),
+    ):
+        _consume_stream_expecting_error(
+            SendMessageRequest(message="hello", chat_session_id=chat_session.id),
+            test_user,
+        )
+
+    db_session.expunge_all()
+    assert _session_row_exists(db_session, chat_session.id)
+    user_messages = (
+        db_session.execute(
+            select(ChatMessage)
+            .where(ChatMessage.chat_session_id == chat_session.id)
+            .where(ChatMessage.message_type == MessageType.USER)
+        )
+        .scalars()
+        .all()
+    )
+    assert len(user_messages) == 1
+    assert user_messages[0].message == "hello"