neovim_config/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common Issues and Solutions

1. Connection Refused Error

Error Message:

Error: Connection refused
Failed to connect to http://localhost:11434

Causes:

• Ollama service is not running
• Ollama is not bound to the correct interface
• Port 11434 is in use by another service

Solutions:

# Check if Ollama is running
ps aux | grep ollama

# If not running, start it
ollama serve

# Or if using systemd
sudo systemctl start ollama
sudo systemctl status ollama

# Check if port is in use
sudo netstat -tlnp | grep 11434
lsof -i :11434

# If another service is using it, either:
# 1. Stop the other service
# 2. Change Ollama port (advanced)

---

2. Model Not Found Error

Error Message:

Error: Model 'mistral' not found

Causes:

• Model hasn't been pulled yet
• Model name is incorrect
• Ollama cache is corrupted

Solutions:

# List available models
curl http://localhost:11434/api/tags | jq '.models[].name'

# Pull the model
ollama pull mistral

# Or pull a different model
ollama pull neural-chat
ollama pull llama2
ollama pull dolphin-mixtral

# Verify it was pulled
ollama list

# If issues persist, remove and re-pull
ollama rm mistral
ollama pull mistral

---

3. Tailscale Connection Issues

Error Message:

Error: Connection refused to 100.x.x.x:11434

Causes:

• Tailscale is not running
• Machines are not on the same Tailscale network
• Firewall is blocking the connection
• Tailscale IP is incorrect

Solutions:

# Check Tailscale status
tailscale status

# If not running, start it
sudo systemctl start tailscaled
tailscale up

# Verify you're logged in
tailscale whoami

# Check your Tailscale IP
tailscale ip -4

# Ping the remote machine
ping 100.x.x.x

# Check if Ollama is accessible from remote
curl http://100.x.x.x:11434/api/tags

# If firewall is blocking, check UFW
sudo ufw status
sudo ufw allow 11434/tcp

---

4. Slow Responses

Symptoms:

• Responses take 30+ seconds
• Neovim appears frozen
• High CPU usage on Ollama server

Causes:

• Model is too large for available resources
• Network latency is high
• Server is running other heavy processes
• Ollama is running on CPU instead of GPU

Solutions:

# Check server resources
top
htop

# Check if Ollama is using GPU
nvidia-smi  # For NVIDIA GPUs
rocm-smi    # For AMD GPUs

# Try a smaller model
ollama pull orca-mini  # 3B model, very fast
ollama pull neural-chat  # 7B model, good balance

# Check network latency
ping 100.x.x.x
# Look for latency > 50ms (indicates network issue)

# Monitor Ollama performance
curl http://localhost:11434/api/tags | jq '.models[] | {name, size}'

# Stop other processes on the server
sudo systemctl stop other-service

---

5. Environment Variable Not Working

Symptoms:

• OLLAMA_ENDPOINT is set but not being used
• Still trying to connect to localhost

Causes:

• Environment variable not exported
• Shell not reloaded after setting variable
• Variable set in wrong shell config file

Solutions:

# Verify the variable is set
echo $OLLAMA_ENDPOINT

# If empty, add to shell config
# For zsh (~/.zshrc):
echo 'export OLLAMA_ENDPOINT="http://100.x.x.x:11434"' >> ~/.zshrc
source ~/.zshrc

# For bash (~/.bashrc):
echo 'export OLLAMA_ENDPOINT="http://100.x.x.x:11434"' >> ~/.bashrc
source ~/.bashrc

# For fish (~/.config/fish/config.fish):
echo 'set -gx OLLAMA_ENDPOINT "http://100.x.x.x:11434"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

# Verify it's set
echo $OLLAMA_ENDPOINT

# Restart Neovim to pick up the new variable

---

6. Ollama Not Accessible from Network

Symptoms:

• Works on localhost
• Fails when connecting from another machine
• curl http://100.x.x.x:11434/api/tags fails

Causes:

• Ollama is only bound to localhost (127.0.0.1)
• Firewall is blocking port 11434
• Network connectivity issue

Solutions:

# Check what Ollama is bound to
sudo netstat -tlnp | grep ollama
# Should show 0.0.0.0:11434 or your IP, not 127.0.0.1:11434

# If bound to localhost only, fix it:
sudo systemctl edit ollama

# Add this line in the [Service] section:
# Environment="OLLAMA_HOST=0.0.0.0:11434"

# Save and restart
sudo systemctl restart ollama

# Verify it's now listening on all interfaces
sudo netstat -tlnp | grep ollama

# Check firewall
sudo ufw status
sudo ufw allow 11434/tcp
sudo ufw reload

# Test from another machine
curl http://100.x.x.x:11434/api/tags

---

7. Neovim CodeCompanion Not Recognizing Ollama

Symptoms:

• Ollama adapter not available
• <leader>cll doesn't work
• Error about unknown adapter

Causes:

• CodeCompanion plugin not loaded
• Ollama adapter not properly configured
• Neovim config not reloaded

Solutions:

" In Neovim:

" Check if CodeCompanion is loaded
:checkhealth codecompanion

" Reload config
:source ~/.config/nvim/init.lua

" Or restart Neovim completely
:qa!
nvim

" Check available adapters
:CodeCompanionChat <Tab>
" Should show: ollama, anthropic, anthropic_opus, anthropic_haiku

" Test the adapter
:CodeCompanionChat ollama Toggle

---

8. Ollama Server Crashes

Symptoms:

• Ollama process dies unexpectedly
• Connection drops mid-conversation
• Out of memory errors

Causes:

• Insufficient RAM
• Model is too large
• System is under heavy load
• Ollama bug

Solutions:

# Check system resources
free -h
df -h

# Check Ollama logs
journalctl -u ollama -n 50
journalctl -u ollama -f  # Follow logs

# Check if model is too large
ollama list
# Compare model size with available RAM

# Reduce model size
ollama rm mistral
ollama pull orca-mini  # Smaller model

# Increase swap (temporary fix)
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Monitor while running
watch -n 1 'free -h && echo "---" && ps aux | grep ollama'

---

9. Timeout Errors

Error Message:

Error: Request timeout
Connection timed out after 30 seconds

Causes:

• Model is taking too long to respond
• Network latency is too high
• Server is overloaded

Solutions:

# Check network latency
ping -c 5 100.x.x.x
# Acceptable: < 50ms
# Marginal: 50-100ms
# Poor: > 100ms

# Try a faster model
ollama pull orca-mini

# Check server load
ssh user@100.x.x.x
top
# Look for high CPU or memory usage

# Reduce concurrent requests
# Only run one CodeCompanion chat at a time

# Increase timeout in CodeCompanion (if supported)
# Check CodeCompanion documentation

---

10. Permission Denied Errors

Error Message:

Error: Permission denied
Cannot access /var/lib/ollama

Causes:

• Ollama service running as different user
• File permissions are incorrect
• SELinux or AppArmor restrictions

Solutions:

# Check Ollama service user
sudo systemctl show -p User ollama

# Fix permissions
sudo chown -R ollama:ollama /var/lib/ollama
sudo chmod -R 755 /var/lib/ollama

# Restart service
sudo systemctl restart ollama

# Check SELinux (if applicable)
getenforce
# If "Enforcing", may need to adjust policies

# Check AppArmor (if applicable)
sudo aa-status | grep ollama

---

Quick Diagnostic Script

#!/bin/bash
# Save as: ~/check_ollama.sh
# Run with: bash ~/check_ollama.sh

echo "=== Ollama Diagnostic Check ==="
echo

echo "1. Ollama Service Status:"
sudo systemctl status ollama --no-pager | head -5
echo

echo "2. Ollama Process:"
ps aux | grep ollama | grep -v grep || echo "Not running"
echo

echo "3. Port Binding:"
sudo netstat -tlnp | grep 11434 || echo "Not listening on 11434"
echo

echo "4. Available Models:"
curl -s http://localhost:11434/api/tags | jq '.models[].name' 2>/dev/null || echo "Cannot connect to Ollama"
echo

echo "5. Tailscale Status:"
tailscale status --self 2>/dev/null || echo "Tailscale not running"
echo

echo "6. System Resources:"
echo "Memory: $(free -h | grep Mem | awk '{print $3 "/" $2}')"
echo "Disk: $(df -h / | tail -1 | awk '{print $3 "/" $2}')"
echo

echo "=== End Diagnostic ==="

---

Getting Help

If you're still having issues:

1. Check the logs:

   journalctl -u ollama -n 100
   

2. Test connectivity:

   curl -v http://localhost:11434/api/tags
   curl -v http://100.x.x.x:11434/api/tags
   

3. Check Neovim messages:

   :messages
   

4. Report issues:

   • Ollama: https://github.com/ollama/ollama/issues
   • CodeCompanion: https://github.com/olimorris/codecompanion.nvim/issues
   • Tailscale: https://github.com/tailscale/tailscale/issues