Troubleshooting Guide

Quick Diagnostics

Check Server Status

curl http://localhost:18080/health

Expected response:

{"status": "ok"}

Verify Provider Health

curl http://localhost:18080/v0/management/heartbeat/status \
  -H "X-Management-Key: your-secret-key"

List Available Models

curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"

Check Logs

# Local deployment
tail -f logs/switchailocal.log

# Docker deployment
docker-compose logs -f switchailocal

Connection Issues

Server Won’t Start

Error: Port Already in Use

Symptom: bind: address already in use or port 18080 conflict.Cause: Another process is using port 18080.Solution:

Find the process using the port:

# Linux/Mac
lsof -i :18080

# Windows
netstat -ano | findstr :18080

Kill the conflicting process or change switchAILocal’s port:
config.yaml
```
port: 18081  # Use a different port
```
Restart switchAILocal:
```
./switchAILocal
```

Error: Config File Not Found

Symptom: config.yaml not found or configuration errors.Cause: Missing or incorrectly named configuration file.Solution:

# Copy the example config
cp config.example.yaml config.yaml

# Edit with your settings
nano config.yaml

Error: Permission Denied on Auth Directory

Symptom: failed to create auth directory or permission errors.Cause: Insufficient permissions for ~/.switchailocal/.Solution:

# Fix permissions
mkdir -p ~/.switchailocal
chmod 700 ~/.switchailocal

# Docker: Fix ownership
sudo chown -R 1000:1000 ~/.switchailocal

Connection Refused

Cannot Connect to Localhost

Symptom: connection refused when making requests.Checklist:

Is the server running? Check with ps aux | grep switchAILocal
Is it listening on the correct port? Verify with lsof -i :18080
Are you using the correct host? Try 127.0.0.1 instead of localhost
Check firewall rules: sudo ufw status

Solution:

# Verify server is running
./ail.sh status

# Restart if needed
./ail.sh restart

Cannot Connect to Ollama

Symptom: failed to connect to Ollama or timeout errors.Solution:

Verify Ollama is running:
```
curl http://localhost:11434/api/tags
```

Check config.yaml:

ollama:
  enabled: true
  base-url: "http://localhost:11434"

For Docker deployments, use host gateway:

ollama:
  base-url: "http://host.docker.internal:11434"

Authentication Errors

OAuth Failures

Error: OAuth Callback Timeout

Symptom: timeout waiting for OAuth callback.Cause: Browser didn’t complete the OAuth flow within the timeout period.Solution:

Ensure port 3000 is available for the callback server
Try the login command again
Complete the browser authorization quickly
Check firewall isn’t blocking localhost:3000

# Verify port 3000 is free
lsof -i :3000

# Retry OAuth login
./switchAILocal --login

Error: Invalid State Parameter

Symptom: OAuth state parameter is invalid.Cause: CSRF token mismatch or expired session.Solution:

Clear OAuth state files:
```
rm -f ~/.switchailocal/oauth_*
```
Retry the login:
```
./switchAILocal --login
```

Error: Client ID/Secret Not Set

Symptom: GEMINI_CLIENT_ID not found or missing credentials.Cause: OAuth environment variables not configured.Solution:Option 1: Use CLI wrappers instead (recommended):

# No OAuth setup needed
# Just use: geminicli:gemini-2.5-pro

Option 2: Set environment variables:

export GEMINI_CLIENT_ID="your-client-id"
export GEMINI_CLIENT_SECRET="your-client-secret"
./switchAILocal --login

API Key Errors

Error: Invalid API Key

Symptom: 401 Unauthorized or invalid api key.Cause: Incorrect or missing API key in requests.Solution:

Verify the API key matches config.yaml:
```
api-keys:
  - "sk-test-123"
```

Include the key in your request:

curl http://localhost:18080/v1/chat/completions \
  -H "Authorization: Bearer sk-test-123" \
  ...

For provider API keys, check they’re correctly formatted:

gemini-api-key:
  - api-key: "AIzaSy..."  # Must start with AIzaSy

claude-api-key:
  - api-key: "sk-ant-..."  # Must start with sk-ant-

Error: Authentication Required

Symptom: Requests fail with authentication errors.Solution:Check which authentication method is configured:

# No config needed - uses CLI tool's auth
# Just use: geminicli:gemini-2.5-pro

Provider Errors

Model Not Found

Error: Model Not Available

Symptom: model not found or no matching provider.Cause: Model not configured or provider prefix incorrect.Solution:

List available models:

curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"

Use correct provider prefix:

# CLI providers
geminicli:gemini-2.5-pro
claudecli:claude-sonnet-4
ollama:llama3.2

# API providers
gemini:gemini-2.5-pro
claude:claude-3-5-sonnet-20241022

Trigger model discovery:

curl -X POST http://localhost:18080/v0/management/discover_models \
  -H "X-Management-Key: your-secret-key"

Error: CLI Command Not Found

Symptom: gemini: command not found or CLI tool errors.Cause: CLI tool not installed or not in PATH.Solution:

Install the CLI tool:

# Google Gemini CLI
npm install -g @google/gemini-cli

# Anthropic Claude CLI
npm install -g @anthropic-ai/claude-cli

# OpenAI Codex CLI
npm install -g @openai/codex-cli

Verify installation:
```
which gemini
gemini --version
```
Authenticate the CLI:
```
gemini auth login
```

Rate Limiting

Error: Rate Limit Exceeded

Symptom: 429 Too Many Requests or rate limit errors.Cause: Exceeded provider API rate limits.Solution:

Configure multiple credentials for load balancing:

config.yaml

gemini-api-key:
  - api-key: "AIzaSy...account1"
  - api-key: "AIzaSy...account2"
  - api-key: "AIzaSy...account3"

routing:
  strategy: "round-robin"

Enable automatic quota rotation:

config.yaml

quota-exceeded:
  switch-project: true
  switch-preview-model: true

Implement retry logic:
config.yaml
```
request-retry: 3
```

Error: Quota Exceeded

Symptom: quota exceeded or billing errors.Cause: API quota limits reached.Solution:

Check quota status:

curl http://localhost:18080/v0/management/quota \
  -H "X-Management-Key: your-secret-key"

Add fallback providers:

config.yaml

intelligence:
  enabled: true
  router-fallback: "ollama:llama3.2"  # Free local fallback

Monitor usage:
config.yaml
```
usage-statistics-enabled: true
```

Request Failures

Timeout Errors

Error: Request Timeout

Symptom: Requests timeout before completion.Cause: Slow provider response or network issues.Solution:

Increase client timeout:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123",
    timeout=120.0  # 2 minutes
)

Check provider health:

curl http://localhost:18080/v0/management/heartbeat/status \
  -H "X-Management-Key: your-secret-key"

Use faster models:

config.yaml

intelligence:
  matrix:
    fast: "gemini-2.0-flash"  # Faster model

Error: Streaming Connection Dropped

Symptom: Streaming responses stop mid-completion.Cause: SSE connection lost or provider timeout.Solution:

Enable keepalive:

config.yaml

streaming:
  keepalive-seconds: 15
  bootstrap-retries: 2

Check network stability
Reduce request complexity (shorter prompts, smaller context)

Response Errors

Error: Malformed JSON Response

Symptom: JSON parsing errors or incomplete responses.Cause: Provider returned invalid JSON or protocol mismatch.Solution:

Enable debug logging:
config.yaml
```
debug: true
logging-to-file: true
```

Check logs for raw responses:

tail -f logs/switchailocal.log | grep "response:"

Verify model supports the requested format

Error: Empty or Null Response

Symptom: API returns empty content or null values.Cause: Provider error, rate limit, or safety filter.Solution:

Check provider status:

curl http://localhost:18080/v0/management/heartbeat/status \
  -H "X-Management-Key: your-secret-key"

Review the request for safety issues (if using content filters)

Try a different provider:

# Original request
{"model": "gemini:gemini-2.5-pro", ...}

# Try alternative
{"model": "claude:claude-3-5-sonnet-20241022", ...}

Cortex Router Issues

Intelligence System

Error: Router Model Not Available

Symptom: router model failed or classification errors.Cause: Configured router model is not available.Solution:

Verify router model exists:

curl http://localhost:18080/v1/models | grep "router-model"

Update router model in config:

config.yaml

intelligence:
  router-model: "ollama:qwen:0.5b"
  router-fallback: "gemini:gemini-2.0-flash"

Use a local model for faster classification:
```
ollama pull qwen:0.5b
```

Error: Semantic Tier Failed

Symptom: Embedding errors or semantic matching failures.Cause: Embedding model not loaded or ONNX runtime missing.Solution:

Download embedding model:
```
./scripts/download-embedding-model.sh
```

Disable semantic tier if not needed:

config.yaml

intelligence:
  embedding:
    enabled: false
  semantic-tier:
    enabled: false

Check ONNX runtime installation:

# Linux
sudo apt-get install libonnxruntime

# macOS
brew install onnxruntime

Skills Not Loading

Symptom: Skills directory errors or skill matching failures.Cause: Skills directory not found or misconfigured.Solution:

Verify skills directory exists:
```
ls -la plugins/cortex-router/skills/
```

Check config path:

config.yaml

intelligence:
  skills:
    enabled: true
    directory: "plugins/cortex-router/skills"

Reload skills:

curl -X POST http://localhost:18080/v0/management/intelligence/reload \
  -H "X-Management-Key: your-secret-key"

Docker-Specific Issues

Container Won't Start

Symptom: Docker container exits immediately.Solution:

Check logs:
```
docker-compose logs switchailocal
```

Verify config.yaml is mounted:

docker-compose exec switchailocal ls -la /app/config.yaml

Check volume permissions:

sudo chown -R 1000:1000 ~/.switchailocal

Cannot Access Host Services

Symptom: Container can’t connect to Ollama/LM Studio on host.Solution:Use host.docker.internal instead of localhost:

config.yaml

ollama:
  enabled: true
  base-url: "http://host.docker.internal:11434"

lmstudio:
  enabled: true
  base-url: "http://host.docker.internal:1234/v1"

Volume Permission Errors

Symptom: Permission denied on mounted volumes.Solution:

# Fix ownership (UID 1000 is the container user)
sudo chown -R 1000:1000 ~/.switchailocal
sudo chown -R 1000:1000 ./logs
sudo chown -R 1000:1000 ./plugins

# Restart container
docker-compose restart switchailocal

Memory System Issues

Memory Stats Not Updating

Symptom: Analytics show stale data or zero values.Cause: Memory system disabled or directory permissions.Solution:

Verify auth directory is writable:
```
ls -la ~/.switchailocal/memory/
```
Check memory files exist:
```
ls -la ~/.switchailocal/memory/*.json
```
Enable usage statistics:
config.yaml
```
usage-statistics-enabled: true
```

Performance Issues

Slow Response Times

Symptom: Requests take longer than expected.Solution:

Use local models for routing:

config.yaml

intelligence:
  router-model: "ollama:qwen:0.5b"  # Fast local classifier

Enable semantic cache:

config.yaml

intelligence:
  semantic-cache:
    enabled: true
    max-size: 10000

Reduce classification overhead:

config.yaml

intelligence:
  semantic-tier:
    enabled: true  # Bypass LLM classification for known patterns

High Memory Usage

Symptom: Process consumes excessive RAM.Solution:

Limit cache sizes:

config.yaml

intelligence:
  semantic-cache:
    max-size: 1000  # Reduce from 10000

Disable unused features:

config.yaml

intelligence:
  embedding:
    enabled: false
  semantic-tier:
    enabled: false

Set Docker resource limits:

docker-compose.yml

deploy:
  resources:
    limits:
      memory: 2G

Getting Help

Debug Mode

Enable verbose logging:

config.yaml

debug: true
logging-to-file: true

Collect Diagnostic Information

# System info
uname -a

# Server version
./switchAILocal --version

# Recent logs
tail -100 logs/switchailocal.log

# Provider health
curl http://localhost:18080/v0/management/heartbeat/status \
  -H "X-Management-Key: your-secret-key"

# Available models
curl http://localhost:18080/v1/models \
  -H "Authorization: Bearer sk-test-123"

Report Issues

If you encounter a bug, please report it with:

Description: What happened vs. what you expected
Steps to Reproduce: Exact commands or API calls
Environment: OS, Docker version, switchAILocal version
Logs: Relevant error messages (with sensitive data removed)
Configuration: Sanitized config.yaml snippet

GitHub Issues: https://github.com/traylinx/switchAILocal/issues

Next Steps

Setup Providers

Configure your AI providers correctly

Management Dashboard

Monitor system health and performance

Get Started

Core Concepts

Configuration

Intelligent Systems

Advanced Features

Guides

Quick Diagnostics

Connection Issues

Server Won’t Start

Connection Refused

Authentication Errors

OAuth Failures

API Key Errors

Provider Errors

Model Not Found

Rate Limiting

Request Failures

Timeout Errors

Response Errors

Cortex Router Issues

Intelligence System

Docker-Specific Issues

Memory System Issues

Performance Issues

Getting Help

Debug Mode

Collect Diagnostic Information

Report Issues

Next Steps

Setup Providers

Management Dashboard

Get Started

Core Concepts

Configuration

Intelligent Systems

Advanced Features

Guides

​Quick Diagnostics

​Connection Issues

​Server Won’t Start

​Connection Refused

​Authentication Errors

​OAuth Failures

​API Key Errors

​Provider Errors

​Model Not Found

​Rate Limiting

​Request Failures

​Timeout Errors

​Response Errors

​Cortex Router Issues

​Intelligence System

​Docker-Specific Issues

​Memory System Issues

​Performance Issues

​Getting Help

​Debug Mode

​Collect Diagnostic Information

​Report Issues

​Next Steps

Setup Providers

Management Dashboard

Quick Diagnostics

Connection Issues

Server Won’t Start

Connection Refused

Authentication Errors

OAuth Failures

API Key Errors

Provider Errors

Model Not Found

Rate Limiting

Request Failures

Timeout Errors

Response Errors

Cortex Router Issues

Intelligence System

Docker-Specific Issues

Memory System Issues

Performance Issues

Getting Help

Debug Mode

Collect Diagnostic Information

Report Issues

Next Steps