Terraphim AI documentation

Troubleshooting Guide

This guide helps you resolve common issues with Terraphim AI across all platforms and installation methods.

🔧 Installation Issues

"cargo install terraphim-agent" fails

Rust Toolchain Issues

Error: error: toolchain 'stable' is not installed Solution: Install Rust toolchain:

curl --proto '=https://sh.rustup.rs' -sSf | sh
source ~/.cargo/env

Compilation Errors

Error: error: failed to compile crate XYZ Solution: Update Rust and try again:

rustup update
rustup install stable

Permission Denied

Error: permission denied: /path/to/.cargo Solution: Check Rust installation directory permissions:

# Fix ownership
sudo chown -R $USER:$(id -gn $USER) ~/.cargo
sudo chmod -R 755 ~/.cargo

# Or use alternative installation
CARGO_HOME=/tmp/.cargo cargo install terraphim-agent

🔍 Search & Query Issues

No Results Found

Empty Search Results

Error: Search returns empty results Solutions:

  1. Check Data Source Configuration:
terraphim-agent config show
# Verify data paths and enabled sources
  1. Verify File Permissions:
# Ensure Terraphim can read your data
chmod -R 644 ~/Documents/your-data
  1. Rebuild Index:
terraphim-agent rebuild-index
# Forces reindexing of all configured sources

Slow Search Performance

Search Taking > 5 Seconds

Solutions:

  1. Check System Resources:
# Check available memory
free -h

# Check disk space
df -h

# Check CPU usage
top -p | grep terraphim
  1. Optimize Configuration:
# In ~/.config/terraphim/config.toml
[performance]
cache_size = "1GB"  # Increase if you have RAM
max_concurrent_queries = 4
  1. Reduce Search Scope:
# Search specific directory only
terraphim-agent search --source local --path "~/specific-folder" "query"

🤖 Desktop Application Issues

"Command not found" Error

Linux/macOS

Error: terraphim-ai-desktop: command not found Solutions:

  1. Use Installation Path:
# Check installation location
which terraphim-ai-desktop

# Run directly if found
/path/to/terraphim-ai-desktop
  1. Reinstall with Package Manager:
# Try system package manager
sudo apt install terraphim-ai-desktop  # Ubuntu/Debian
brew install --cask terraphim-ai-desktop  # macOS

Application Won't Start

Windows Issues

Error: "Application failed to start properly" Solutions:

  1. Check Windows Defender:
  • Add Terraphim to exclusions
  • Allow through firewall
  1. Install Visual C++ Redistributable:
  • Download from Microsoft website
  • Restart computer
  1. Run as Administrator:
  • Right-click → "Run as administrator"

🌐 Network & API Issues

GitHub Integration Problems

Rate Limiting

Error: "API rate limit exceeded" Solutions:

  1. Configure Authentication:
[sources.github]
token = "your-github-token"  # Create at github.com/settings/tokens
  1. Reduce Concurrent Requests:
[sources.github]
max_concurrent_requests = 3
rate_limit_delay = 1000  # milliseconds

Ollama Connection Issues

Connection Refused

Error: "Connection refused" when connecting to Ollama Solutions:

  1. Check Ollama Status:
ollama list
# Should show available models
  1. Verify Ollama Running:
ps aux | grep ollama
# Check if Ollama process is running
  1. Start Ollama Service:
# Linux
systemctl --user start ollama

# macOS
brew services start ollama

# Manual start
ollama serve

Quickwit Log Search Issues

Connection Refused

Error: "Failed to connect to Quickwit" Solutions:

  1. Verify Quickwit is Running:
curl http://localhost:7280/health
# Should return: "ok"

curl http://localhost:7280/api/v1/indexes
# Should return list of available indexes
  1. Check API Path Prefix: Quickwit uses /api/v1/ path prefix (not /v1/):
# Correct
curl http://localhost:7280/api/v1/indexes

# Incorrect (will return "Route not found")
curl http://localhost:7280/v1/indexes
  1. Authentication Issues:
# Test Basic Auth
curl -u username:password http://localhost:7280/api/v1/indexes

# Test Bearer token
curl -H "Authorization: Bearer your-token" http://localhost:7280/api/v1/indexes

No Results from Auto-Discovery

Error: "No indexes discovered" Solutions:

  1. Verify Indexes Exist:
curl http://localhost:7280/api/v1/indexes | jq '.[].index_config.index_id'
  1. Check Index Filter Pattern: If using index_filter, ensure pattern matches:
  • workers-* matches workers-logs, workers-metrics
  • *-logs matches api-logs, service-logs
  • * matches all indexes
  1. Try Explicit Index:
{
  "extra_parameters": {
    "default_index": "your-index-name"
  }
}

Empty Search Results

Error: Query returns no documents Solutions:

  1. Test Direct Search:
curl "http://localhost:7280/api/v1/workers-logs/search?query=*&max_hits=10"
  1. Verify Query Syntax:
# Simple text search
/search error

# Field-specific search
/search "level:ERROR"

# Time range (requires timestamp field)
/search "timestamp:[2024-01-01 TO *]"
  1. Check Sort Field: If using -timestamp sort, ensure the field exists in your index schema.

🧠 Memory & Performance Issues

High Memory Usage

Memory Leak Detection

Symptoms: Memory usage increases continuously over time Solutions:

  1. Monitor Memory Usage:
# Watch Terraphim memory usage
watch -n 5 'ps aux | grep terraphim-agent | grep -v grep | awk "{print \$6}"'
  1. Reduce Cache Size:
[persistence]
cache_size = "256MB"  # Reduce from default
cache_ttl = 3600  # Reduce cache time
  1. Restart Periodically:
# Use cron to restart daily
0 2 * * * pkill -f terraphim-agent && sleep 2 && terraphim-agent &

🔐 Authentication & Security Issues

API Key Problems

OpenRouter Integration

Error: "Invalid API key or authentication failed" Solutions:

  1. Verify API Key Format:
  • Keys start with sk-
  • No extra spaces or line breaks
  1. Check Environment Variables:
echo $OPENROUTER_API_KEY
# Should show your key without trailing newline
  1. Test API Key:
curl -X POST https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "meta-llama/llama-3.1-8b", "messages": [{"role": "user", "content": "test"}]}'

📋 Data Source Issues

Local File Indexing Problems

Large File Handling

Error: "File too large to process" Solutions:

  1. Exclude Large Files:
[sources.local_files]
exclude_patterns = ["*.log", "*.db", "node_modules/*", "target/*"]
max_file_size = "50MB"
  1. Optimize File Types:
[sources.local_files]
binary_extensions = [".zip", ".tar.gz", ".mp4", ".pdf"]
index_binaries = false

Git Repository Issues

Repository Not Found

Error: "Failed to clone repository" Solutions:

  1. Check Repository URL:
# Test repository accessibility
git ls-remote https://github.com/user/repo.git
  1. Use SSH Instead of HTTPS:
# Configure SSH for GitHub
git config --global [email protected]:.insteadOf https://github.com/

🔄 Update & Auto-Update Issues

Update Process Fails

Update Download Failed

Error: "Failed to download update" Solutions:

  1. Check Network Connectivity:
curl -I https://releases.terraphim.ai
# Should return 200 OK
  1. Manual Update:
# Download latest version manually
wget https://releases.terraphim.ai/latest/terraphim-agent-linux-x64
chmod +x terraphim-agent-linux-x64
sudo ./terraphim-agent-linux-x64 --install
  1. Disable Auto-Update:
[updates]
auto_check = false
# Check manually with: terraphim-agent update --check

🐛 Error Codes Reference

Exit Codes

| Code | Meaning | Solution | |-------|----------|----------| | 1 | General Error | Check error message for details | | 2 | File Not Found | Verify file paths and permissions | | 3 | Permission Denied | Run with appropriate permissions | | 4 | Network Error | Check network connectivity and configuration | | 5 | Configuration Error | Validate config file syntax and values | | 6 | Memory Error | Check available RAM and reduce cache sizes | | 7 | LLM Error | Verify API keys and model availability |

Log Locations

Finding Logs

# Rust CLI logs
~/.local/share/terraphim/logs/
tail -f ~/.local/share/terraphim/logs/terraphim-agent.log

# Desktop application logs
# Linux
~/.local/share/terraphim-ai-desktop/logs/
# macOS
~/Library/Logs/terraphim-ai-desktop/
# Windows
%APPDATA%/terraphim-ai-desktop/logs/

Log Levels

# Enable debug logging
export TERRAPHIM_LOG=debug
terraphim-agent search "test"

# Enable trace logging
export TERRAPHIM_LOG=trace
terraphim-agent search "test"

🚨 Emergency Procedures

Reset to Defaults

If Terraphim becomes unresponsive or corrupted:

# Backup current configuration
cp ~/.config/terraphim/config.toml ~/terraphim-config-backup.toml

# Reset to defaults
rm -rf ~/.config/terraphim/
terraphim-agent init

# Restore custom settings
cp ~/terraphim-config-backup.toml ~/.config/terraphim/config.toml

Complete Reinstall

# Remove all traces
rm -rf ~/.config/terraphim/
rm -rf ~/.local/share/terraphim/
cargo uninstall terraphim-agent

# Clean reinstall
cargo install terraphim-agent

📞 Getting Additional Help

Community Support

  1. Discord Community: Join our Discord

    • Real-time help from community
    • Weekly office hours with maintainers
    • User discussions and tips

  2. GitHub Discussions: Start a Discussion

    • Detailed technical discussions
    • Feature requests and suggestions
    • Community knowledge base

  3. GitHub Issues: Report an Issue

    • Bug reports and feature requests
    • Technical support from maintainers
    • Track issue resolution progress

Professional Support

  1. Documentation: Full Documentation

    • Comprehensive guides and API reference
    • Troubleshooting steps and examples
    • Architecture and integration guides

  2. Email Support: [email protected]

    • Enterprise and professional support
    • Priority response for business users
    • Security vulnerability reporting

🔧 Diagnostic Commands

System Information Collection

Before reporting issues, collect this information:

# System information
terraphim-agent --version
uname -a
lsb_release -a 2>/dev/null || echo "Not Ubuntu/Debian"

# Rust information
rustc --version
cargo --version

# Memory and disk
free -h
df -h

# Network test
curl -I https://api.github.com
curl -I https://openrouter.ai

# Save to file
terraphim-agent --diagnostic-info > terraphim-diagnostic.txt

Include this diagnostic information when reporting issues for faster resolution.

Last Updated: December 20, 2025 Version: Terraphim AI v1.3.0 Part of: Terraphim AI Documentation Suite

Quickwit Log Exploration Guide Phase 5 Verification Documentation Index