wp-agentic-writer/docs/user-facing/downloads/agentic-writer-local-backend/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions for Agentic Writer Local Backend.

Connection Issues

"Connection timeout" in Plugin

Symptoms:

• Plugin shows "Connection timeout" error
• Test connection fails

Solutions:

1. Check proxy is running:

   ps aux | grep claude-proxy
   

2. Restart proxy:

   ./stop-proxy.sh
   ./start-proxy.sh
   

3. Check logs:

   tail -f proxy.log
   

4. Verify IP address:

   ./get-local-ip.sh
   

"Connection refused"

Cause: Proxy not running or wrong IP

Solutions:

1. Start proxy:

   ./start-proxy.sh
   

2. Check firewall:

   • macOS: System Settings → Network → Firewall → Allow Node.js
   • Linux: sudo ufw allow 8080/tcp
   • Windows: Defender Firewall → Allow port 8080

3. Test locally first:

   curl http://localhost:8080/ping
   # Should return: pong
   

Claude CLI Issues

"Claude CLI not found"

Verify installation:

which claude
# macOS: /opt/homebrew/bin/claude or /usr/local/bin/claude
# Linux: ~/.local/bin/claude or /usr/bin/claude

Fix PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="/opt/homebrew/bin:$PATH"
source ~/.zshrc

Reinstall Claude CLI:

• Visit: https://claude.ai/code
• Follow installation instructions

"No response from Claude"

Test Claude manually:

echo "Hello, reply with: Test successful" | claude

Check authentication:

claude --version
# Should show version and auth status

Reconfigure Claude:

• Check Z.ai account: https://z.ai
• Or Anthropic API key setup

Network Issues

Wrong IP Address Detected

Find correct IP:

# macOS
ipconfig getifaddr en0    # WiFi
ipconfig getifaddr en1    # Ethernet

# Linux
ip route get 1 | awk '{print $7}'
hostname -I

# Windows
ipconfig
# Look for "IPv4 Address" under active adapter

Update plugin settings:

• Use the correct IP in Base URL: http://CORRECT-IP:8080

Port 8080 Already in Use

Find what's using it:

lsof -i :8080
# or
netstat -anp | grep 8080

Change port:

1. Edit claude-proxy.js:

   const PORT = process.env.PORT || 9000; // Change 8080 to 9000
   

2. Restart proxy:

   ./stop-proxy.sh
   PORT=9000 ./start-proxy.sh
   

3. Update plugin Base URL: http://your-ip:9000

Performance Issues

Slow Response Times

Normal latency:

• Local network: 50-200ms
• Claude CLI processing: 2-30 seconds depending on prompt

If consistently slow:

1. Check network:

   ping 192.168.1.105  # Your proxy IP
   

2. Monitor logs:

   tail -f proxy.log
   

3. Check machine resources:

   • CPU usage: Claude CLI is CPU-intensive
   • Memory: Ensure sufficient RAM available

Proxy Crashes

Check logs:

cat proxy.log | tail -50

Common causes:

• Out of memory: Close other applications
• Claude CLI timeout: Increase timeout in claude-proxy.js
• Malformed requests: Check plugin version compatibility

Restart with clean state:

./stop-proxy.sh
rm proxy.log
./start-proxy.sh

Plugin Integration Issues

"Invalid response format"

Cause: Claude response doesn't match expected JSON format

Debug:

1. Check proxy.log for actual Claude output

2. Test manually:

   curl -X POST http://localhost:8080/v1/messages \
     -H "Content-Type: application/json" \
     -d '{"messages":[{"role":"user","content":"Hello"}]}'
   

3. Update Claude CLI if outdated:

   claude --version
   # Upgrade if needed
   

Cost Tracking Shows $0

Expected behavior: Local backend is free, plugin should show $0.00 (Local)

If concerned:

• This is correct - local backend has no API costs
• Dashboard should show "X requests local (free)"

Advanced Troubleshooting

Enable Debug Logging

Edit claude-proxy.js:

const DEBUG = true; // Add at top of file

// In /v1/messages handler:
if (DEBUG) {
    console.log('Full request:', JSON.stringify(req.body, null, 2));
    console.log('Full response:', output);
}

Test with curl

Ping:

curl http://localhost:8080/ping
# Expected: pong

Inference:

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Reply with: Test successful"}
    ]
  }'

Expected response:

{
  "id": "local-1234567890",
  "object": "chat.completion",
  "model": "claude-local",
  "choices": [{
    "message": {
      "content": "Test successful"
    }
  }]
}

Permissions Issues (macOS)

Make scripts executable:

chmod +x start-proxy.sh stop-proxy.sh test-connection.sh get-local-ip.sh

If "permission denied":

# Check file permissions
ls -la *.sh

# Reset if needed
chmod 755 *.sh

Still Having Issues?

1. Check system requirements:

   • Node.js 18+: node --version
   • Claude CLI installed: which claude
   • Sufficient disk space: df -h

2. Collect diagnostic info:

   echo "Node version:" $(node --version)
   echo "Claude path:" $(which claude)
   echo "Local IP:" $(./get-local-ip.sh)
   echo "Proxy status:" $(ps aux | grep claude-proxy)
   tail -20 proxy.log
   

3. Reset everything:

   ./stop-proxy.sh
   rm -rf node_modules proxy.log proxy.pid
   npm install
   ./start-proxy.sh
   

4. Get help:

   • GitHub Issues: Report Bug
   • Discord Community: Join Chat
   • Include: OS, Node version, Claude CLI version, error logs

Environment-Specific Notes

macOS

• Default Claude path: /opt/homebrew/bin/claude
• Firewall: System Settings → Network → Firewall
• IP detection: ipconfig getifaddr en0

Linux

• Default Claude path: ~/.local/bin/claude
• Firewall: sudo ufw allow 8080/tcp
• IP detection: ip route get 1 | awk '{print $7}'

Windows

• Claude path varies, check where claude
• Firewall: Windows Defender → Allow port 8080
• IP detection: ipconfig (look for IPv4)
• Scripts: Use Git Bash or WSL to run .sh scripts

Security Best Practices

1. LAN only: Don't expose proxy to internet without authentication
2. Firewall: Restrict to specific IPs if on shared network
3. Logs: proxy.log contains all prompts - review periodically
4. Updates: Keep Node.js and Claude CLI updated

---

Last Updated: 2025-02-27
Version: 1.0.0