Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(db): carry operation and errno on DatabaseSessionUnavailableError (#7710)

Imaduddin Bhaisaheb9ed3e0747ff0
diff --git a/changelog.d/7685.bugfix.md b/changelog.d/7685.bugfix.md
new file mode 100644
index 0000000000..c615c6f162
--- /dev/null
+++ b/changelog.d/7685.bugfix.md
@@ -0,0 +1,6 @@
+`DatabaseSessionUnavailableError.reason` now carries the same scrub-safe
+fields the login route logs for a rekey sidecar or epoch fault: the fault's
+type name plus the sidecar operation and errno when it has them (for example
+`RekeySidecarIOError (operation=open, errno=24)`), instead of the type name
+alone. Both paths build the text with the shared `describe_rekey_fault`
+helper, and it never includes path material or OS error text.
diff --git a/src/local_deep_research/database/rekey_lock.py b/src/local_deep_research/database/rekey_lock.py
index 87540fb7f9..08f07fc8da 100644
--- a/src/local_deep_research/database/rekey_lock.py
+++ b/src/local_deep_research/database/rekey_lock.py
@@ -188,6 +188,27 @@ class RekeyEpochUnreadableError(RekeyRecoveryRequiredError):
self.errno = error_number
+def describe_rekey_fault(error: RekeyOperationalError) -> str:
+ """Scrub-safe ``type (operation=..., errno=...)`` summary of a rekey fault.
+
+ Shared by the login route's log line and ``DatabaseSessionUnavailableError``
+ so an operator sees the same fields for the same fault on either path.
+ Only the exception's type name, the closed ``RekeySidecarOperation`` value
+ and the numeric errno are used. Never a path, the OS error text or the
+ exception message, which may carry path material.
+ """
+ fields: list[str] = []
+ if isinstance(error, RekeySidecarIOError):
+ fields.append(f"operation={error.operation.value}")
+ if isinstance(error, (RekeySidecarIOError, RekeyEpochUnreadableError)):
+ error_number = error.errno
+ fields.append(
+ f"errno={'unknown' if error_number is None else error_number}"
+ )
+ name = type(error).__name__
+ return f"{name} ({', '.join(fields)})" if fields else name
+
+
@dataclass(frozen=True, slots=True)
class RekeyEpochState:
"""Durable committed and in-flight rekey generations."""
diff --git a/src/local_deep_research/database/session_context.py b/src/local_deep_research/database/session_context.py
index 3d3a71086e..84c2c58dea 100644
--- a/src/local_deep_research/database/session_context.py
+++ b/src/local_deep_research/database/session_context.py
@@ -14,7 +14,7 @@ from sqlalchemy.orm import Session
from ..security.log_sanitizer import scrub_error
from ..utilities.thread_context import get_search_context
from .encrypted_db import db_manager
-from .rekey_lock import RekeyOperationalError
+from .rekey_lock import RekeyOperationalError, describe_rekey_fault
from .thread_local_session import thread_session_manager
# Placeholder password used when accessing unencrypted databases.
@@ -42,9 +42,12 @@ class DatabaseSessionUnavailableError(DatabaseSessionError):
the session instead (``database_unavailable_exception`` in
``web/dependencies/auth.py``).
- ``reason`` is the underlying fault's type name, for diagnostics. The
- fault itself is neither chained nor kept: the frames it was raised
- through hold the plaintext password.
+ ``reason`` is the underlying fault's scrub-safe summary, for diagnostics:
+ its type name plus the sidecar operation and errno when the fault carries
+ them (``RekeySidecarIOError (operation=open, errno=24)``), the same fields
+ the login route logs for the same fault class (``describe_rekey_fault``).
+ It never holds path material. The fault itself is neither chained nor
+ kept: the frames it was raised through hold the plaintext password.
"""
def __init__(self, reason: str) -> None:
@@ -258,7 +261,7 @@ def get_user_db_session(
try:
session = get_metrics_session(username, password)
except RekeyOperationalError as error:
- unavailable_reason = type(error).__name__
+ unavailable_reason = describe_rekey_fault(error)
if unavailable_reason is not None:
logger.warning(
f"Database session unavailable for {username}: {unavailable_reason}"
diff --git a/src/local_deep_research/web/routers/auth.py b/src/local_deep_research/web/routers/auth.py
index e3d844a4ae..44258d028e 100644
--- a/src/local_deep_research/web/routers/auth.py
+++ b/src/local_deep_research/web/routers/auth.py
@@ -31,7 +31,7 @@ from ...database.rekey_lock import (
RekeyIndeterminateError,
RekeyLockContentionError,
RekeyOperationalError,
- RekeySidecarIOError,
+ describe_rekey_fault,
)
from ...database.models.auth import User
from ...database.thread_local_session import thread_cleanup
@@ -307,16 +307,10 @@ def login(
# past the open's wait bound (RekeyLockContentionError). Credentials
# cannot be validated in any of these cases, so fail closed WITHOUT
# counting toward lockout — the password may well be correct.
- sidecar_detail = ""
- if isinstance(error, RekeySidecarIOError):
- sidecar_detail = (
- f" (sidecar {error.operation.value} failed, "
- f"errno={error.errno})"
- )
+ fault_summary = describe_rekey_fault(error)
logger.warning(
f"Login refused for {redact_and_bound_for_log(username, 50)}: "
- f"rekey state requires operator attention "
- f"({type(error).__name__}){sidecar_detail}"
+ f"rekey state requires operator attention ({fault_summary})"
)
flash(
request,
diff --git a/tests/database/test_sidecar_fault_probe.py b/tests/database/test_sidecar_fault_probe.py
index 5765ca43da..365f72d2e2 100644
--- a/tests/database/test_sidecar_fault_probe.py
+++ b/tests/database/test_sidecar_fault_probe.py
@@ -669,7 +669,14 @@ def test_get_user_db_session_reports_a_sidecar_fault_as_unavailable(
assert isinstance(
raised.value, session_context_module.DatabaseSessionUnavailableError
)
- assert raised.value.reason == "RekeySidecarIOError"
+ # Same scrub-safe fields the login route logs for this fault class:
+ # type name, sidecar operation and errno (EMFILE), and no path material.
+ # The sidecar open is the first fault; the second claim's fault
+ # surfaces from its own operation, so only the shape is pinned there.
+ assert raised.value.reason.startswith("RekeySidecarIOError (operation=")
+ assert f"errno={errno.EMFILE})" in raised.value.reason
+ assert str(db_path) not in raised.value.reason
+ assert db_path.name not in raised.value.reason
# Neither chained nor kept as context: the frames the fault came
# through hold the plaintext password.
assert raised.value.__cause__ is None
@@ -1287,3 +1294,46 @@ def test_a_planted_fifo_cannot_hang_the_probe_or_the_shutdown(
assert "error" not in outcome, outcome
assert "alice" not in manager.connections
engine.dispose.assert_called_once_with()
+
+
+ ("error", "expected"),
+ [
+ (
+ rekey_lock_module.RekeySidecarIOError(
+ Path("/secret/user.db"),
+ rekey_lock_module.RekeySidecarOperation.ACQUIRE,
+ errno.EACCES,
+ ),
+ f"RekeySidecarIOError (operation=acquire, errno={errno.EACCES})",
+ ),
+ (
+ rekey_lock_module.RekeySidecarIOError(
+ Path("/secret/user.db"),
+ rekey_lock_module.RekeySidecarOperation.OPEN,
+ None,
+ ),
+ "RekeySidecarIOError (operation=open, errno=unknown)",
+ ),
+ (
+ rekey_lock_module.RekeyEpochUnreadableError(
+ Path("/secret/user.db"), errno.EIO
+ ),
+ f"RekeyEpochUnreadableError (errno={errno.EIO})",
+ ),
+ (
+ rekey_lock_module.RekeyRecoveryRequiredError(
+ Path("/secret/user.db")
+ ),
+ "RekeyRecoveryRequiredError",
+ ),
+ ],
+)
+def test_describe_rekey_fault_is_scrub_safe(
+ error: rekey_lock_module.RekeyOperationalError, expected: str
+) -> None:
+ described = rekey_lock_module.describe_rekey_fault(error)
+
+ assert described == expected
+ assert "secret" not in described
+ assert "user.db" not in described