diff --git a/docs/install.md b/docs/install.md
index a2dcef064e..3fee56ab0b 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -94,6 +94,8 @@ To install Nextflow with the self-installing package:
 
     :::{warning}
     Nextflow updates its executable during the self-install process, therefore the update can fail if the executable is placed in a directory with restricted permissions.
+
+    Avoid installing the `nextflow` executable into a root-owned location such as `/usr/local/bin` with `sudo` if you plan to use `nextflow self-update`. If the executable is not writable by your normal user account, self-updates can fail and may leave the installation in a broken state. Prefer a user-writable location such as `$HOME/.local/bin`.
     :::
 
 4. Confirm Nextflow is installed correctly:
diff --git a/docs/updating-nextflow.md b/docs/updating-nextflow.md
index d0d1bdf86d..8bae8a85b8 100644
--- a/docs/updating-nextflow.md
+++ b/docs/updating-nextflow.md
@@ -34,8 +34,17 @@ When updating from an edge release to a stable release, you must explicitly set
 
 :::{warning}
 Nextflow will update its executable during the self-update process. The update can fail if the Nextflow executable is in a directory with restricted permissions.
+
+Do not run `nextflow self-update` with `sudo`. If the executable or framework directory becomes owned by `root`, subsequent Nextflow commands can fail with `Permission denied` errors for your normal user account.
 :::
 
+If `self-update` fails after a `sudo` install or update, recover the installation with the following steps:
+
+1. Remove the root-owned framework directory for the affected version, for example `sudo rm -rf ~/.nextflow/framework/<version>`.
+2. If needed, remove or replace a root-owned `nextflow` executable that was installed into a protected location such as `/usr/local/bin`.
+3. Reinstall Nextflow in a user-writable location such as `$HOME/.local/bin`.
+4. Run `nextflow info` or `nextflow -v` to confirm the installation works again.
+
 ## Version selection
 
 The `NXF_VER` environment variable can be used to define which version of Nextflow to use. To switch to a specific version of Nextflow for a single run, set the `NXF_VER` environment variable in your execution command. For example: