diff --git a/README.md b/README.md
index f7c2ca2..be85b2a 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,27 @@ go build ./...
 go test ./...
 ```
 
+### Troubleshooting Go dependency downloads
+
+If you see an error like:
+
+```text
+GOPROXY list is not the empty string, but contains no entries
+```
+
+your local Go environment is misconfigured. A common fix is:
+
+```bash
+go env -w GOPROXY=https://proxy.golang.org,direct
+```
+
+Helpful diagnostics:
+
+```bash
+go env GOPROXY
+echo "$GOPROXY"
+```
+
 ### Acceptance tests
 
 Acceptance tests are read-only and opt-in.
diff --git a/codex/setup.sh b/codex/setup.sh
index 0127b5a..d6170a2 100755
--- a/codex/setup.sh
+++ b/codex/setup.sh
@@ -14,6 +14,33 @@ for cmd in bash git; do
   have "$cmd" || die "$cmd is required"
 done
 
+validate_goproxy() {
+  local value="$1"
+  local part trimmed
+  local has_valid=0
+
+  IFS=',' read -r -a parts <<<"$value"
+  for part in "${parts[@]}"; do
+    trimmed="${part#"${part%%[![:space:]]*}"}"
+    trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
+    if [[ -n "$trimmed" ]]; then
+      has_valid=1
+      break
+    fi
+  done
+
+  if [[ "$has_valid" -eq 0 ]]; then
+    warn "GOPROXY appears malformed: non-empty value contains no entries"
+    warn "This can cause errors like: GOPROXY list is not the empty string, but contains no entries"
+    warn "Suggested fix: go env -w GOPROXY=https://proxy.golang.org,direct"
+    warn "Current GOPROXY from environment: '$value'"
+  fi
+}
+
+if [[ "${GOPROXY+x}" == "x" ]]; then
+  validate_goproxy "$GOPROXY"
+fi
+
 ensure_dir .codex
 ensure_dir .codex/bin
 ensure_dir .codex/cache
diff --git a/scripts/setup-dev.sh b/scripts/setup-dev.sh
index e482353..2dd09cc 100755
--- a/scripts/setup-dev.sh
+++ b/scripts/setup-dev.sh
@@ -11,6 +11,33 @@ for cmd in bash git go; do
   echo "[setup-dev] $cmd: $(command -v "$cmd")"
 done
 
+validate_goproxy() {
+  local value="$1"
+  local part trimmed
+  local has_valid=0
+
+  IFS=',' read -r -a parts <<<"$value"
+  for part in "${parts[@]}"; do
+    trimmed="${part#"${part%%[![:space:]]*}"}"
+    trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
+    if [[ -n "$trimmed" ]]; then
+      has_valid=1
+      break
+    fi
+  done
+
+  if [[ "$has_valid" -eq 0 ]]; then
+    echo "[setup-dev][warn] GOPROXY appears malformed: non-empty value contains no entries." >&2
+    echo "[setup-dev][warn] This can cause errors like: GOPROXY list is not the empty string, but contains no entries." >&2
+    echo "[setup-dev][warn] Suggested fix: go env -w GOPROXY=https://proxy.golang.org,direct" >&2
+    echo "[setup-dev][warn] Current GOPROXY from environment: '$value'" >&2
+  fi
+}
+
+if [[ "${GOPROXY+x}" == "x" ]]; then
+  validate_goproxy "$GOPROXY"
+fi
+
 if command -v terraform >/dev/null 2>&1; then
   echo "[setup-dev] terraform: $(command -v terraform)"
 else