From a4f4f32e22c687a3b51a84a7701c6fce5b0a8ca5 Mon Sep 17 00:00:00 2001
From: caubet_m <marc.caubet@psi.ch>
Date: Tue, 27 May 2025 12:24:02 +0200
Subject: [PATCH] Add common problems

---
 .../99-support/migration-from-merlin6.md      | 56 ++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/pages/merlin7/99-support/migration-from-merlin6.md b/pages/merlin7/99-support/migration-from-merlin6.md
index 71695a5..be9fb96 100644
--- a/pages/merlin7/99-support/migration-from-merlin6.md
+++ b/pages/merlin7/99-support/migration-from-merlin6.md
@@ -135,9 +135,19 @@ This script will:
 
   * `migrate_merlin6data.batch` (data dir)
   * `migrate_merlin6home.batch` (home dir)
+    * This job will only start if `migrate_merlin6data.batch` has successfully
+      finished.
 * Automatically track the job IDs
 * Print log file locations for the different jobs
 
+If something goes wrong:
+* Users have to check the reason in the job logs and fix it.
+* Please read [⚠️ Common rsync/fpsync Migration Issues](/merlin7/migrating.html#%EF%B8%8F--common-rsyncfpsync-migration-issues)
+  to see how to solve some of the commonest problems.
+* If `migrate_merlin6data.batch` fails, `migrate_merlin6home.batch` will be cancelled.
+* **Once the issues are fixed, users should restart the migration with `merlin7_migration.start`**
+  * Migration will continue.
+
 > ⚠️ **Once both transfers succeed, your access to Merlin6 will be revoked.**
 > Do **not** attempt to reconnect to Merlin6 after this.
 
@@ -216,7 +226,7 @@ Submitting transfer jobs to Slurm
    tmux new-session -d -s "xfersession" "watch 'squeue -M merlin6 -u caubet_m -p xfer'"
    tmux attach -t "xfersession"
 
-✅ FINISHED
+✅ FINISHED - PLEASE CHECK JOB TRANSFER PROGRESS
 ```
 
 ### Monitor Progress
@@ -235,6 +245,50 @@ CLUSTER: merlin6
           24688580      xfer DATA_MIG caubet_m  R       0:22      1 merlin-c-017
 ```
 
+## ⚠️  Common `rsync`/`fpsync` Migration Issues
+
+### File Permission Denied
+
+* **Cause**: Files or directories are not readable by the user running the transfer.
+* **Solution**: Fix source-side permissions:
+
+  ```bash
+  chmod -R u+rX /path/to/file_or_dir
+  ```
+
+### Ownership Mismatches
+
+* **Cause**: Source files are owned by another user (e.g. root or a collaborator).
+* **Solution**:
+
+  * Change ownership before migration:
+
+    ```bash
+    chown -R $USER /path/to/file
+    ```
+
+### Special Files (e.g. device files, sockets)
+
+* **Cause**: `rsync` tries to copy UNIX sockets, device files, or FIFOs.
+* **Effect**: Errors or incomplete copies.
+* **Solution**: Avoid transferring such files entirely (by deleting them).
+
+### Exceeded Disk Quota
+
+* **Cause**: Combined size of existing + incoming data exceeds 1 TB quota on Merlin7.
+* **Effect**: Transfer stops abruptly.
+* **Solution**: Clean up or archive non-essential data before migration.
+
+### Very Small Files or Large Trees → Many Small rsync Calls
+
+* **Cause**: Directory with thousands/millions of small files.
+* **Effect**: Transfer is slow or hits process limits.
+* **Solution**: Consider archiving to `.tar.gz` before transferring:
+
+  ```bash
+  tar -czf myenv.tar.gz myenv/
+  ```
+
 ---
 
 ## 📬 Need Help?