diff --git a/docs/antora.yml b/docs/antora.yml
index 89ec6b5a..2d7224ec 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -6,6 +6,7 @@ nav:
 - modules/ROOT/pages/getting-started/_nav.adoc
 - modules/ROOT/pages/how-tos/_nav.adoc
 - modules/ROOT/pages/advanced-how-tos/_nav.adoc
+- modules/ROOT/pages/troubleshooting/_nav.adoc
 - modules/ROOT/pages/glossary/_nav.adoc
 - modules/ROOT/pages/contribute/_nav.adoc
 
diff --git a/docs/modules/ROOT/pages/troubleshooting/_nav.adoc b/docs/modules/ROOT/pages/troubleshooting/_nav.adoc
new file mode 100644
index 00000000..5c93c3ce
--- /dev/null
+++ b/docs/modules/ROOT/pages/troubleshooting/_nav.adoc
@@ -0,0 +1 @@
+* xref:troubleshooting/index.adoc[Troubleshooting]
diff --git a/docs/modules/ROOT/pages/troubleshooting/index.adoc b/docs/modules/ROOT/pages/troubleshooting/index.adoc
new file mode 100644
index 00000000..03bffffe
--- /dev/null
+++ b/docs/modules/ROOT/pages/troubleshooting/index.adoc
@@ -0,0 +1,33 @@
+= Troubleshooting
+
+== No space left on device
+
+Tasks may fail with an error message mentioning `No space left on device` as the underlying error.
+This likely means your build pipeline wrote more data than expected into a shared volume.
+
+Typically seen in the `clone-repository` or `prefetch-dependencies` task in a build pipeline.
+
+For the clone task, the error message may look similar to:
+
+[source,text]
+----
+[clone] {"level":"error","ts":1721904304.0047252,"caller":"git/git.go:53","msg":"Error running git [checkout -f FETCH_HEAD]: exit status 128\nerror: unable to write file ...: No space left on device\n"
+----
+
+The device that's running out of space is most likely the workspace declared in your `PipelineRun`
+YAML files. *The solution is to request more disk space.* In the `.spec.workspaces` section in
+all the relevant PipelineRun files, increase the storage request.
+
+[source,yaml]
+----
+spec:
+  # ...
+  workspaces:
+    # ...
+    - name: workspace
+      volumeClaimTemplate:
+        spec:
+          resources:
+            requests:
+              storage: 1Gi  # increase accordingly
+----