From e5bb3f7dbb8769bada5fc2aa026f3d2a0f6b5a25 Mon Sep 17 00:00:00 2001
From: stumpylog <797416+stumpylog@users.noreply.github.com>
Date: Thu, 29 Oct 2026 15:03:07 -0700
Subject: [PATCH] Fix: surface the database error when refreshing a document
 before moving its files

---
 src/documents/signals/handlers.py         | 12 ++++++------
 src/documents/tests/test_file_handling.py | 23 +++++++++++++++++++++++
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/src/documents/signals/handlers.py b/src/documents/signals/handlers.py
index f6a318c0e..9c20e97f2 100644
--- a/src/documents/signals/handlers.py
+++ b/src/documents/signals/handlers.py
@@ -476,13 +476,13 @@ def update_filename_and_move_files(
         return
 
     with FileLock(settings.MEDIA_LOCK):
-        try:
-            # If this was waiting for the lock, the filename or archive_filename
-            # of this document may have been updated.  This happens if multiple updates
-            # get queued from the UI for the same document
-            # So freshen up the data before doing anything
-            instance.refresh_from_db()
+        # If this was waiting for the lock, the filename or archive_filename
+        # of this document may have been updated.  This happens if multiple updates
+        # get queued from the UI for the same document
+        # So freshen up the data before doing anything
+        instance.refresh_from_db()
 
+        try:
             old_filename = instance.filename
             old_source_path = instance.source_path
             move_original = False
diff --git a/src/documents/tests/test_file_handling.py b/src/documents/tests/test_file_handling.py
index 46c54f98f..74dff9bcc 100644
--- a/src/documents/tests/test_file_handling.py
+++ b/src/documents/tests/test_file_handling.py
@@ -2134,3 +2134,26 @@ class TestPathDateLocalization:
         with override_settings(FILENAME_FORMAT=filename_format):
             filename = generate_filename(document)
             assert filename == Path(expected_filename)
+
+
+@pytest.mark.django_db
+def test_refresh_failure_surfaces_database_error(paperless_dirs) -> None:
+    """
+    GIVEN:
+        - A document with a stored filename
+    WHEN:
+        - Saving it triggers a filename update and refreshing it from the database fails
+    THEN:
+        - The database error is raised, not an unbound variable error from the rollback
+    """
+    document = DocumentFactory(filename="some.pdf")
+
+    with (
+        mock.patch.object(
+            Document,
+            "refresh_from_db",
+            side_effect=DatabaseError("database is locked"),
+        ),
+        pytest.raises(DatabaseError, match="database is locked"),
+    ):
+        document.save()