claude-code-termux/docs/TROUBLESHOOTING.md

# Troubleshooting

## /tmp Permission Denied

**Error:** `EACCES: permission denied, mkdir '/tmp/claude/...'`

**Cause:** Claude Code hardcodes `/tmp` for background tasks. Termux doesn't have `/tmp`.

**Fix:** Always start Claude via `clauded`, which uses `termux-chroot` to provide a working `/tmp`.

```bash
# Wrong
claude

# Right
clauded
```

**Why not proot?** `proot -b $PREFIX/tmp:/tmp` only affects the main process. Child processes (Bash tool, agents) run in separate shells without the binding. `termux-chroot` simulates a full FHS where `/tmp -> /usr/tmp` works for ALL processes.

---

## Native Binary Error (v2.1.113+)

**Error:** `claude native binary not installed`

**Cause:** Starting with v2.1.113, Anthropic migrated from `cli.js` (pure Node.js) to native binaries (SEA). Termux reports `process.platform === 'android'` which is not supported.

**Why no workaround:**
- `npm install --force` of linux-arm64 downloads the binary but needs `/lib/ld-linux-aarch64.so.1` (glibc) or `/lib/ld-musl-aarch64.so.1` (musl)
- Termux uses Bionic libc (Android), neither linker exists
- `termux-chroot` and `proot` don't help because the linkers simply don't exist

**Fix:** Stay on v2.1.112 (last pure Node.js release).

```bash
claude-update  # Automatically respects the version ceiling
```

**How to verify a version is compatible:**
```bash
npm pack @anthropic-ai/claude-code@VERSION --dry-run 2>&1 | grep cli.js
# If cli.js (~13MB) appears -> compatible
# If cli-wrapper.cjs (~4KB) appears -> native binary, NOT compatible
```

---

## Auto-updater Bypasses Settings

**Problem:** Claude Code may auto-update despite `DISABLE_AUTOUPDATER=1`.

**Fix:** Protect the installation directory:
```bash
chmod -R a-w $PREFIX/lib/node_modules/@anthropic-ai/claude-code/
```

To update later, unprotect first:
```bash
chmod -R u+w $PREFIX/lib/node_modules/@anthropic-ai/claude-code/
claude-update
```

---

## SSH .local Resolution Fails

**Error:** `ssh hostname.local` fails with "Could not resolve hostname"

**Cause:** mDNS (.local) does NOT work natively in Termux (Android's Bionic libc doesn't support it).

**Fix:** Install the companion repo
[**mdns-termux**](https://devops.ingeniumcodex.com/andresgarcia0313/mdns-termux)
which provides `ssh-mdns-proxy` (mDNS → Tailscale → cache) and the generic
`resolve` command usable in any tool (ping, curl, kubectl…).

---

## Sharp/Image Support

**Warning:** `Sharp WASM not installed (no image support)`

**Fix:**
```bash
npm install -g @img/sharp-wasm32 sharp --force
```

This enables Claude Code to process images (screenshots, diagrams, etc.).

---

## Alternative: proot-distro

For running newer Claude Code versions (v2.1.113+), you can use proot-distro with Ubuntu, which provides real glibc:

```bash
pkg install proot-distro
proot-distro install ubuntu
proot-distro login ubuntu
# Inside Ubuntu: install node, npm, claude-code@latest
```

**Trade-offs:** +2GB disk, slight performance overhead, but full Linux compatibility.