diff --git a/docs/JENKINS.md b/docs/JENKINS.md
index c4dcbe6..165ef8d 100644
--- a/docs/JENKINS.md
+++ b/docs/JENKINS.md
@@ -54,3 +54,32 @@ Install the **Gitea** plugin in Jenkins, then use **Gitea** as the branch source
 - Archives `dist/docker-compose.coolify.yml`
 
 This validates the repo; **Coolify deploy is separate**.
+
+## Troubleshooting
+
+### `fatal: not in a git directory` (branch indexing)
+
+Usually a **corrupt Jenkins git cache** after changing container user. In the **jenkins** container terminal (Coolify):
+
+```bash
+rm -rf /var/jenkins_home/caches/git-*
+chown -R jenkins:jenkins /var/jenkins_home
+```
+
+Then **Scan Repository Now** on the multibranch job.
+
+### `permission denied` on `/var/run/docker.sock`
+
+Jenkins must be in the host **docker** group. On the Coolify host:
+
+```bash
+stat -c '%g' /var/run/docker.sock
+```
+
+Set that number as `DOCKER_GID` on the **jenkins** Coolify service (default `999`), redeploy Jenkins, rebuild.
+
+Do **not** run Jenkins as `user: 0:0` — it breaks `jenkins_home` ownership and git caches.
+
+### Always use **Build Now** on `main`, not **Rebuild** on old builds
+
+Old rebuilds replay old commits with old `Jenkinsfile` content.