diff --git a/README.md b/README.md
index adb24867d8..9cfe981caa 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ which comes with $50 in free credits for new users.
 
 ## 💻 Running OpenHands Locally
 
-OpenHands can also run on your laptop using Docker.
+OpenHands can also run on your local system using Docker.
 See the [Running OpenHands](https://docs.all-hands.dev/modules/usage/installation) guide for
 system requirements and more information.
 
diff --git a/docs/modules/usage/how-to/cli-mode.md b/docs/modules/usage/how-to/cli-mode.md
index 9e10a4a34a..adeb520fd3 100644
--- a/docs/modules/usage/how-to/cli-mode.md
+++ b/docs/modules/usage/how-to/cli-mode.md
@@ -50,3 +50,6 @@ docker run -it \
 ```
 
 This command will start an interactive session in Docker where you can input tasks and receive responses from OpenHands.
+
+The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s
+permissions. This prevents the agent from creating root-owned files in the mounted workspace.
diff --git a/docs/modules/usage/how-to/headless-mode.md b/docs/modules/usage/how-to/headless-mode.md
index 640e60e5a6..f8836ecb6e 100644
--- a/docs/modules/usage/how-to/headless-mode.md
+++ b/docs/modules/usage/how-to/headless-mode.md
@@ -47,6 +47,9 @@ docker run -it \
     python -m openhands.core.main -t "write a bash script that prints hi"
 ```
 
+The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s
+permissions. This prevents the agent from creating root-owned files in the mounted workspace.
+
 ## Advanced Headless Configurations
 
 To view all available configuration options for headless mode, run the Python command with the `--help` flag.
diff --git a/docs/modules/usage/runtimes/docker.md b/docs/modules/usage/runtimes/docker.md
index a51131258f..0b24e017e8 100644
--- a/docs/modules/usage/runtimes/docker.md
+++ b/docs/modules/usage/runtimes/docker.md
@@ -35,8 +35,8 @@ A useful feature is the ability to connect to your local filesystem. To mount yo
 Be careful! There's nothing stopping the OpenHands agent from deleting or modifying
 any files that are mounted into its workspace.
 
-This setup can cause some issues with file permissions (hence the `SANDBOX_USER_ID` variable)
-but seems to work well on most systems.
+The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s
+permissions. This prevents the agent from creating root-owned files in the mounted workspace.
 
 ## Hardened Docker Installation
 
diff --git a/docs/modules/usage/troubleshooting/troubleshooting.md b/docs/modules/usage/troubleshooting/troubleshooting.md
index 6dfdda90a1..70232db8f3 100644
--- a/docs/modules/usage/troubleshooting/troubleshooting.md
+++ b/docs/modules/usage/troubleshooting/troubleshooting.md
@@ -20,3 +20,18 @@ Try these in order:
 * If using Docker Desktop, ensure `Settings > Advanced > Allow the default Docker socket to be used` is enabled.
 * Depending on your configuration you may need `Settings > Resources > Network > Enable host networking` enabled in Docker Desktop.
 * Reinstall Docker Desktop.
+
+### Permission Error
+
+**Description**
+
+On initial prompt, an error is seen with `Permission Denied` or `PermissionError`.
+
+**Resolution**
+
+* Check if the `~/.openhands-state` is owned by `root`. If so, you can:
+  * Change the directory's ownership: `sudo chown <user>:<user> ~/.openhands-state`.
+  * or update permissions on the directory: `sudo chmod 777 ~/.openhands-state`
+  * or delete it if you don’t need previous data. OpenHands will recreate it. You'll need to re-enter LLM settings.
+* If mounting a local directory, ensure your `WORKSPACE_BASE` has the necessary permissions for the user running
+  OpenHands.