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.

docs(rekey): clarify transient contention during pending recovery (#7692)

Chanhyo Jung15df3e0ef8d4
diff --git a/changelog.d/7691.misc.md b/changelog.d/7691.misc.md
new file mode 100644
index 0000000000..ad48ab13c3
--- /dev/null
+++ b/changelog.d/7691.misc.md
@@ -0,0 +1 @@
+Clarify when pending-rekey recovery errors call for retrying transient contention rather than manual recovery.
diff --git a/docs/security/rekey-recovery.md b/docs/security/rekey-recovery.md
index 948340630f..9a1e36bace 100644
--- a/docs/security/rekey-recovery.md
+++ b/docs/security/rekey-recovery.md
@@ -127,8 +127,21 @@ Login refused for <user>: rekey state requires operator attention (RekeySidecarI
| `RekeyLockContentionError` | Another holder kept the user's `.rekey.lock` for more than 5 seconds: a password change of a large database, another worker's cold open, a stopped process or a hung mount | Yes, when the holder finishes |
| `RekeySidecarIOError` | `.rekey.lock` could not be opened or locked, or an epoch file could not be written (`operation` is `open`, `acquire`, `unlock`, `close` or `publish`; check the errno: `ENOSPC`, `EROFS`, `EACCES`, `EMFILE`, `ELOOP` for a symlink, `EINVAL` for a non-regular file, `EMLINK` for an already-unlinked lock file or one hard-linked to another file in the same directory) | Once the cause is fixed |
| `RekeyEpochUnreadableError` | An epoch file exists but cannot be read (I/O error, permissions, a symlink or non-regular file planted at its name) | Once the cause is fixed |
-| `DatabaseKeyCheckUnavailableError` | The database could not be opened to check the password: SQLite reported it locked or busy past the busy timeout (`db_config.busy_timeout_ms`), an I/O error, or a file it cannot open. The password was not checked, so no lockout strike is counted | Yes, once the lock holder finishes or the I/O problem is fixed |
-| `RekeyRecoveryRequiredError` | The epoch files do not vouch for a stable state: a malformed token, `.rekey.pending` without `.rekey.epoch`, or the password opened the database but committing the pending epoch failed (often disk full) | No, if the files are malformed: see below |
+| `DatabaseKeyCheckUnavailableError` | Outside pending-rekey recovery, the database could not be opened to check the password: SQLite reported it locked or busy past the busy timeout (`db_config.busy_timeout_ms`), an I/O error, or a file it cannot open. The password was not checked, so no lockout strike is counted | Yes, once the lock holder finishes or the I/O problem is fixed |
+| `RekeyRecoveryRequiredError` | The epoch files do not vouch for a stable state (a malformed token or `.rekey.pending` without `.rekey.epoch`), or pending-rekey recovery failed while opening/verifying the surviving key or publishing the pending epoch. Recovery also wraps SQLite busy/locked errors during key proof in this type | Yes for transient contention once the lock holder finishes; persistent failures or malformed metadata need attention (see below) |
+
+`RekeyRecoveryRequiredError` alone does not establish that the password was
+verified or that the epoch files are malformed. During pending-rekey
+recovery, a key-proof failure can be wrapped in this type before a password
+verdict is available. It still produces the login 503 above, without a
+lockout strike; this is not an invalid-password response.
+
+For transient contention, let the lock holder finish and retry the login
+before attempting manual recovery. Use [manual recovery](#manual-recovery)
+only if the 503 persists after the underlying cause is fixed, or if the
+epoch files are malformed. Do not delete the rekey files to bypass a
+transient lock; the server-stop, backup and file-protection requirements
+below still apply.
## Related log lines
diff --git a/src/local_deep_research/database/encrypted_db.py b/src/local_deep_research/database/encrypted_db.py
index 63cae4cc0c..7916fc0dfa 100644
--- a/src/local_deep_research/database/encrypted_db.py
+++ b/src/local_deep_research/database/encrypted_db.py
@@ -2859,9 +2859,12 @@ class DatabaseManager:
Returns False when ``password`` does not open the surviving key: an
ordinary wrong password, which callers must treat exactly like any
other failed credential (the login route counts it toward the
- lockout). Only a password that opens the database but whose
- verification or epoch publication fails raises
- ``RekeyRecoveryRequiredError``.
+ lockout). Other failures while opening or verifying the surviving key
+ or publishing the pending epoch raise ``RekeyRecoveryRequiredError``.
+ This includes transient SQLite busy/locked errors during key proof,
+ before a password verdict is available. The error type alone proves
+ neither successful password verification nor malformed epoch metadata;
+ the login route answers it with 503 and no lockout strike.
"""
pending_epoch = state.pending_epoch
if pending_epoch is None:
@@ -2879,6 +2882,8 @@ class DatabaseManager:
commit_rekey_epoch(db_path, pending_epoch)
clear_pending_rekey_epoch(db_path, pending_epoch)
except Exception:
+ # This also wraps key-proof contention before a password verdict;
+ # the type alone does not establish malformed epoch metadata.
raise RekeyRecoveryRequiredError(db_path) from None
finally:
if connection is not None: