107 lines
2.9 KiB
Markdown
107 lines
2.9 KiB
Markdown
# 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:** Use the included `ssh-mdns-proxy` as ProxyCommand in `~/.ssh/config`:
|
|
```
|
|
Host *.local
|
|
ProxyCommand ~/.local/bin/ssh-mdns-proxy %h %p
|
|
```
|
|
|
|
This uses pure Python multicast UDP to resolve mDNS, with Tailscale DNS fallback.
|
|
|
|
---
|
|
|
|
## 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.
|