From 0e94055d271afbbc7f1c68475a1c084cd144cb18 Mon Sep 17 00:00:00 2001
From: TW <tw@waldmann-edv.de>
Date: Wed, 13 May 2026 09:48:34 +0200
Subject: [PATCH] docs: document error handling in borg create, fixes #4912

---
 src/borg/archiver.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/borg/archiver.py b/src/borg/archiver.py
index 38ff43408..c95da4477 100644
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -3748,6 +3748,20 @@ class Archiver:
         Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended.
 
 
+        Error handling
+        ++++++++++++++
+ 
+        When Borg encounters a file or directory it cannot read (e.g., due to permission
+        denied, or another process holding an exclusive lock on Windows), it will:
+ 
+        - Log a warning message.
+        - Skip that file or directory and continue backing up the remaining files.
+        - Exit with a Warning RC at the end of the operation.
+ 
+        This ensures that a single problematic file does not abort your entire backup.
+        You should check your logs for these warnings to ensure that all important data
+        is being backed up.
+ 
         .. _list_item_flags:
 
         Item flags