# 08 — Troubleshooting & Corporate Proxy

> Common issues, Forcepoint proxy workarounds, MLX warnings, and fixes.

---

## Corporate Proxy (Forcepoint CertChecker)

This machine is behind an AT&T Forcepoint proxy that performs SSL deep packet inspection.

### Proxy Details

| Setting   | Value                                         |
| --------- | --------------------------------------------- |
| Proxy URL | `http://cso.proxy.att.com:8080/`              |
| Agent     | Forcepoint CertChecker                        |
| Impact    | Intercepts HTTPS, replaces TLS certificates   |
| Env vars  | `HTTP_PROXY`, `HTTPS_PROXY` set automatically |

### What Works Through Proxy

| Tool                       | Status     | Notes                                       |
| -------------------------- | ---------- | ------------------------------------------- |
| `ollama pull`              | ✅ Works   | Ollama handles proxy natively               |
| `brew install`             | ✅ Works   | Homebrew handles proxy                      |
| `npm install`              | ✅ Works   | With `NODE_TLS_REJECT_UNAUTHORIZED=0`       |
| `git clone` (GitHub)       | ✅ Works   | With `GIT_SSL_NO_VERIFY=1`                  |
| `pip install` (PyPI)       | ✅ Works   | Via corporate Artifactory mirror            |
| **`hf-mirror.com`**        | ✅ Works   | Chinese HuggingFace mirror, **not blocked** |
| `curl` to Hugging Face     | ❌ Blocked | Returns 19 KB HTML redirect page            |
| `curl -k` to Hugging Face  | ❌ Blocked | Still intercepted even with `-k`            |
| `python requests` to HF    | ❌ Blocked | SSL_CERTIFICATE_VERIFY_FAILED               |
| `huggingface_hub` download | ❌ Blocked | Falls back to cached (broken) files         |

### Workaround 1: Use hf-mirror.com (recommended)

`hf-mirror.com` is a Chinese mirror of HuggingFace that **is NOT blocked** by Forcepoint. Replace `huggingface.co` with `hf-mirror.com` in any download URL:

```bash
# Instead of:  https://huggingface.co/org/model/resolve/main/file.bin
# Use:         https://hf-mirror.com/org/model/resolve/main/file.bin

# Example: download SNAC decoder (TTS)
curl -k -L -o models/snac_24khz/pytorch_model.bin \
    "https://hf-mirror.com/hubertsiuzdak/snac_24khz/resolve/main/pytorch_model.bin"

# Example: download Whisper model
curl -k -L -o ~/whisper-models/ggml-large-v3-turbo.bin \
    "https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin"
```

The TTS scripts (`setup-tts.sh`, `download-tts-models.sh`) use this mirror automatically.

### Workaround 2: Download Off-Network

If the mirror is also blocked, use a non-corporate network:

1. **Disconnect** from corporate VPN/Wi-Fi
2. **Connect** to personal hotspot or home Wi-Fi
3. Run the download:
   ```bash
   curl -L -o ~/whisper-models/ggml-large-v3-turbo.bin \
     https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
   ```
4. **Reconnect** to corporate. The model is stored locally forever.

### Detecting a Proxy-Corrupted Download

If a download completed but the file is suspiciously small:

```bash
# Check file size (should be ~1.6 GB for large-v3-turbo)
ls -lh ~/whisper-models/ggml-large-v3-turbo.bin

# Check file type (should NOT be HTML)
file ~/whisper-models/ggml-large-v3-turbo.bin

# If it says "HTML document text" — delete and re-download off-network
rm ~/whisper-models/ggml-large-v3-turbo.bin
```

---

## Ollama Issues

### `MLX dynamic library not available`

```
WARN MLX dynamic library not available error="failed to load MLX dynamic library"
```

**Severity:** Harmless
**Cause:** Ollama searches for Apple MLX framework but it's not installed
**Impact:** None — falls back to Metal backend which is fully functional on M4 Pro
**Fix:** None needed. Ignore the warning.

### Model Pull Fails (SSL / Proxy)

```bash
# Try bypassing proxy for Ollama registry
NO_PROXY="ollama.com,registry.ollama.ai" ollama pull llama3.1:8b
```

### Ollama Not Responding

```bash
# Check if running
curl http://localhost:11434/api/tags

# Restart
brew services restart ollama
# or
pkill ollama && ollama serve
```

### JSON Parse Errors in Evals

Model returned markdown-wrapped JSON (` ```json ... ``` `). Fix by adding to your prompt:

```
Return ONLY a valid JSON object — no markdown, no backticks, no explanation.
```

### Slow Inference

Check Activity Monitor — Ollama should be using GPU (Metal). If CPU-only:

```bash
# Restart with performance flags
OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0 ollama serve
```

### Model Won't Unload from RAM

```bash
# Force unload via API
curl http://localhost:11434/api/generate -d '{"model": "MODEL_NAME", "prompt": "", "keep_alive": "0"}'

# Or restart Ollama entirely
brew services restart ollama
```

### Disk Space Running Low

```bash
# Check Ollama disk usage
du -sh ~/.ollama/models/

# List models with sizes
ollama list

# Remove models you don't need
ollama rm <model-name>
```

---

## Whisper.cpp Issues

### `command not found: whisper-cpp`

The binary is named `whisper-cli`, NOT `whisper-cpp`:

```bash
# Wrong
whisper-cpp --model ...

# Correct
whisper-cli --model ...
```

Full list of binaries: `ls /opt/homebrew/bin/whisper-*`

### Audio Format Not Supported

Whisper.cpp requires WAV format. Convert first:

```bash
# m4a → wav (16kHz mono)
ffmpeg -i input.m4a -ar 16000 -ac 1 output.wav

# mp3 → wav
ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav
```

### Model File Is HTML (Proxy-Corrupted)

```bash
file ~/whisper-models/ggml-large-v3-turbo.bin
# If output says "HTML document text" — it's corrupted
rm ~/whisper-models/ggml-large-v3-turbo.bin
# Re-download off corporate network
```

### `ffmpeg: command not found`

```bash
brew install ffmpeg
```

---

## Dashboard Issues

### Port Conflict

```bash
# Default port 3100, change if needed
npm run dev -- -p 3101
```

### Lockfile Warning

```
Warning: Next.js inferred your workspace root, but it may not be correct.
We detected multiple lockfiles...
```

This is harmless — the dashboard has its own `package-lock.json` inside the pnpm monorepo. Can be silenced by adding `turbopack.root` to `next.config.ts`.

### API Routes Return Empty Data

- **Ollama offline:** Start with `ollama serve` or `brew services start ollama`
- **Whisper not installed:** Run `brew install whisper-cpp`
- **No models:** Check `ollama list` and `ls ~/whisper-models/`

---

## General macOS Issues

### Accessibility / Permissions

Some tools (e.g., `whisper-stream` for mic access) need explicit macOS permissions:

System Settings → Privacy & Security → Microphone → enable Terminal / your IDE

### Node.js TLS Warning

```
Warning: Setting NODE_TLS_REJECT_UNAUTHORIZED to '0' makes TLS connections insecure
```

This is set in the corporate environment to handle Forcepoint proxy. Harmless for local dev.