Mathis/llamactl

Fork 0

mirror of https://github.com/lordmathis/llamactl.git synced 2025-11-06 00:54:23 +00:00

Files

LordMathis bd31c03f4a Create initial documentation structure

2025-09-02 22:05:01 +02:00

9.6 KiB

Raw Blame History

Troubleshooting

Common issues and solutions for LlamaCtl deployment and operation.

Installation Issues

Binary Not Found

Problem: llamactl: command not found

Solutions:

Verify the binary is in your PATH:
```
echo $PATH
which llamactl
```

Add to PATH or use full path:

export PATH=$PATH:/path/to/llamactl
# or
/full/path/to/llamactl

Check binary permissions:
```
chmod +x llamactl
```

Permission Denied

Problem: Permission errors when starting LlamaCtl

Solutions:

Check file permissions:
```
ls -la llamactl
chmod +x llamactl
```

Verify directory permissions:

# Check models directory
ls -la /path/to/models/

# Check logs directory
sudo mkdir -p /var/log/llamactl
sudo chown $USER:$USER /var/log/llamactl

Run with appropriate user:

# Don't run as root unless necessary
sudo -u llamactl ./llamactl

Startup Issues

Port Already in Use

Problem: bind: address already in use

Solutions:

Find process using the port:

sudo netstat -tulpn | grep :8080
# or
sudo lsof -i :8080

Kill the conflicting process:
```
sudo kill -9 <PID>
```
Use a different port:
```
llamactl --port 8081
```

Configuration Errors

Problem: Invalid configuration preventing startup

Solutions:

Validate configuration file:

llamactl --config /path/to/config.yaml --validate

Check YAML syntax:
```
yamllint config.yaml
```

Use minimal configuration:

server:
  host: "localhost"
  port: 8080

Instance Management Issues

Model Loading Failures

Problem: Instance fails to start with model loading errors

Diagnostic Steps:

Check model file exists:

ls -la /path/to/model.gguf
file /path/to/model.gguf

Verify model format:

# Check if it's a valid GGUF file
hexdump -C /path/to/model.gguf | head -5

Test with llama.cpp directly:

llama-server --model /path/to/model.gguf --port 8081

Common Solutions:

Corrupted model: Re-download the model file
Wrong format: Ensure model is in GGUF format
Insufficient memory: Reduce context size or use smaller model
Path issues: Use absolute paths, check file permissions

Memory Issues

Problem: Out of memory errors or system becomes unresponsive

Diagnostic Steps:

Check system memory:
```
free -h
cat /proc/meminfo
```
Monitor memory usage:
```
top -p $(pgrep llamactl)
```

Check instance memory requirements:

curl http://localhost:8080/api/instances/{name}/stats

Solutions:

Reduce context size:

{
  "options": {
    "context_size": 1024
  }
}

Enable memory mapping:

{
  "options": {
    "no_mmap": false
  }
}

Use quantized models:
- Try Q4_K_M instead of higher precision models
- Use smaller model variants (7B instead of 13B)

GPU Issues

Problem: GPU not detected or not being used

Diagnostic Steps:

Check GPU availability:
```
nvidia-smi
```
Verify CUDA installation:
```
nvcc --version
```
Check llama.cpp GPU support:
```
llama-server --help | grep -i gpu
```

Solutions:

Install CUDA drivers:

sudo apt update
sudo apt install nvidia-driver-470 nvidia-cuda-toolkit

Rebuild llama.cpp with GPU support:
```
cmake -DLLAMA_CUBLAS=ON ..
make
```

Configure GPU layers:

{
  "options": {
    "gpu_layers": 35
  }
}

Performance Issues

Slow Response Times

Problem: API responses are slow or timeouts occur

Diagnostic Steps:

Check API response times:

time curl http://localhost:8080/api/instances

Monitor system resources:
```
htop
iotop
```

Check instance logs:

curl http://localhost:8080/api/instances/{name}/logs

Solutions:

Optimize thread count:

{
  "options": {
    "threads": 6
  }
}

Adjust batch size:

{
  "options": {
    "batch_size": 512
  }
}

Enable GPU acceleration:

{
  "options": {
    "gpu_layers": 35
  }
}

High CPU Usage

Problem: LlamaCtl consuming excessive CPU

Diagnostic Steps:

Identify CPU-intensive processes:
```
top -p $(pgrep -f llamactl)
```

Check thread allocation:

curl http://localhost:8080/api/instances/{name}/config

Solutions:

Reduce thread count:

{
  "options": {
    "threads": 4
  }
}

Limit concurrent instances:
```
limits:
  max_instances: 3
```

Network Issues

Connection Refused

Problem: Cannot connect to LlamaCtl web interface

Diagnostic Steps:

Check if service is running:
```
ps aux | grep llamactl
```
Verify port binding:
```
netstat -tulpn | grep :8080
```
Test local connectivity:
```
curl http://localhost:8080/api/health
```

Solutions:

Check firewall settings:
```
sudo ufw status
sudo ufw allow 8080
```

Bind to correct interface:

server:
  host: "0.0.0.0"  # Instead of "localhost"
  port: 8080

CORS Errors

Problem: Web UI shows CORS errors in browser console

Solutions:

Enable CORS in configuration:

server:
  cors_enabled: true
  cors_origins:
    - "http://localhost:3000"
    - "https://yourdomain.com"

Use reverse proxy:

server {
    listen 80;
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Database Issues

Startup Database Errors

Problem: Database connection failures on startup

Diagnostic Steps:

Check database service:

systemctl status postgresql
# or
systemctl status mysql

Test database connectivity:

psql -h localhost -U llamactl -d llamactl

Solutions:

Start database service:

sudo systemctl start postgresql
sudo systemctl enable postgresql

Create database and user:

CREATE DATABASE llamactl;
CREATE USER llamactl WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE llamactl TO llamactl;

Web UI Issues

Blank Page or Loading Issues

Problem: Web UI doesn't load or shows blank page

Diagnostic Steps:

Check browser console for errors (F12)

Verify API connectivity:

curl http://localhost:8080/api/system/status

Check static file serving:
```
curl http://localhost:8080/
```

Solutions:

Clear browser cache
Try different browser
Check for JavaScript errors in console
Verify API endpoint accessibility

Authentication Issues

Problem: Unable to login or authentication failures

Diagnostic Steps:

Check authentication configuration:

curl http://localhost:8080/api/config | jq .auth

Verify user credentials:

# Test login endpoint
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'

Solutions:

Reset admin password:
```
llamactl --reset-admin-password
```
Disable authentication temporarily:
```
auth:
  enabled: false
```

Log Analysis

Enable Debug Logging

For detailed troubleshooting, enable debug logging:

logging:
  level: "debug"
  output: "/var/log/llamactl/debug.log"

Key Log Patterns

Look for these patterns in logs:

Startup issues:

ERRO Failed to start server
ERRO Database connection failed
ERRO Port binding failed

Instance issues:

ERRO Failed to start instance
ERRO Model loading failed
ERRO Process crashed

Performance issues:

WARN High memory usage detected
WARN Request timeout
WARN Resource limit exceeded

Getting Help

Collecting Information

When seeking help, provide:

System information:
```
uname -a
llamactl --version
```
Configuration:
```
llamactl --config-dump
```
Logs:
```
tail -100 /var/log/llamactl/app.log
```
Error details:
- Exact error messages
- Steps to reproduce
- Environment details

Support Channels

GitHub Issues: Report bugs and feature requests
Documentation: Check this documentation first
Community: Join discussions in GitHub Discussions

Preventive Measures

Health Monitoring

Set up monitoring to catch issues early:

# Regular health checks
*/5 * * * * curl -f http://localhost:8080/api/health || alert

Resource Monitoring

Monitor system resources:

# Disk space monitoring
df -h /var/log/llamactl/
df -h /path/to/models/

# Memory monitoring
free -h

Backup Configuration

Regular configuration backups:

# Backup configuration
cp ~/.llamactl/config.yaml ~/.llamactl/config.yaml.backup

# Backup instance configurations
curl http://localhost:8080/api/instances > instances-backup.json

Next Steps

Set up Monitoring to prevent issues
Learn about Advanced Configuration
Review Best Practices

9.6 KiB Raw Blame History

Troubleshooting

Installation Issues

Binary Not Found

Permission Denied

Startup Issues

Port Already in Use

Configuration Errors

Instance Management Issues

Model Loading Failures

Memory Issues

GPU Issues

Performance Issues

Slow Response Times

High CPU Usage

Network Issues

Connection Refused

CORS Errors

Database Issues

Startup Database Errors

Web UI Issues

Blank Page or Loading Issues

Authentication Issues

Log Analysis

Enable Debug Logging

Key Log Patterns

Getting Help

Collecting Information

Support Channels

Preventive Measures

Health Monitoring

Resource Monitoring

Backup Configuration

Next Steps

9.6 KiB

Raw Blame History