diff --git a/skills/cmux-browser/SKILL.md b/skills/cmux-browser/SKILL.md
index 8d398377..33e6d47d 100644
--- a/skills/cmux-browser/SKILL.md
+++ b/skills/cmux-browser/SKILL.md
@@ -114,3 +114,21 @@ These commands currently return `not_supported` because they rely on Chrome/CDP-
 - low-level raw input injection
 
 Use supported high-level commands (`click`, `fill`, `press`, `scroll`, `wait`, `snapshot`) instead.
+
+## Troubleshooting
+
+### `js_error` on `snapshot --interactive` or `eval`
+
+Some complex pages can reject or break the JavaScript used for rich snapshots and ad-hoc evaluation.
+
+Recovery steps:
+
+```bash
+cmux browser surface:7 get url
+cmux browser surface:7 get text body
+cmux browser surface:7 get html body
+```
+
+- Use `get url` first so you know whether the page actually navigated.
+- Fall back to `get text body` or `get html body` when `snapshot --interactive` or `eval` returns `js_error`.
+- If the page is still failing, navigate to a simpler intermediate page, then retry the task from there.
diff --git a/tests_v2/test_browser_skill_js_error_docs.py b/tests_v2/test_browser_skill_js_error_docs.py
new file mode 100644
index 00000000..566ab10f
--- /dev/null
+++ b/tests_v2/test_browser_skill_js_error_docs.py
@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Regression checks for cmux-browser js_error troubleshooting docs."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from cmux import cmuxError
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SKILL = ROOT / "skills/cmux-browser/SKILL.md"
+
+
+def _must(cond: bool, msg: str) -> None:
+    if not cond:
+        raise cmuxError(msg)
+
+
+def main() -> int:
+    skill = SKILL.read_text(encoding="utf-8")
+
+    _must("## Troubleshooting" in skill, "Expected Troubleshooting section in cmux-browser skill")
+    _must("### `js_error` on `snapshot --interactive` or `eval`" in skill, "Expected js_error troubleshooting heading")
+    _must("cmux browser surface:7 get url" in skill, "Expected get url recovery step")
+    _must("cmux browser surface:7 get text body" in skill, "Expected get text body recovery step")
+    _must("cmux browser surface:7 get html body" in skill, "Expected get html body recovery step")
+    _must("when `snapshot --interactive` or `eval` returns `js_error`" in skill, "Expected js_error fallback guidance")
+    _must("navigate to a simpler intermediate page" in skill, "Expected simpler-page fallback guidance")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())