From d1f4f58bd565cb89d2663a84be9c22342c9916a5 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 27 Oct 2026 12:22:13 +0000
Subject: [PATCH] docs: explain eCryptfs image-pull failures

Image pulls on Linux can fail with an I/O error when sandbox state is on eCryptfs. Add troubleshooting guidance that identifies the diagnostic warning and recommends another filesystem for state.
---
 content/manuals/ai/sandboxes/troubleshooting.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md
index 2b84b98f5c..03e631cebc 100644
--- a/content/manuals/ai/sandboxes/troubleshooting.md
+++ b/content/manuals/ai/sandboxes/troubleshooting.md
@@ -28,6 +28,14 @@ with suggested fixes. Use `--json` or `--format yaml` for machine-readable
 output, or `--format github-issue` to generate a Markdown snippet suitable for pasting
 into a GitHub issue.
 
+## Image pulls fail on eCryptfs
+
+On Linux, image pulls can fail with an I/O error when the sandbox state
+directory is on eCryptfs.
+
+If [`sbx diagnose`](#run-diagnostics) reports `state directory is on eCryptfs`,
+use a filesystem other than eCryptfs for sandbox state.
+
 ## Sandbox is not responding
 
 If `sbx ls` shows `running (not responding)`, Docker Sandboxes has detected