Troubleshooting

Troubleshooting Guide

This guide covers common issues you might encounter with Thought Ledger and their solutions.

Installation Issues

Ollama Installation Fails

Problem: Ollama installation script fails or doesn’t complete.

Solutions:

# Try manual installation
# macOS
brew install ollama

# Linux
curl -L https://ollama.com/download/ollama-linux-amd64 -o ollama
chmod +x ollama
sudo mv ollama /usr/local/bin/

# Start Ollama service
ollama serve

Check system requirements:

• Ensure you have admin/sudo privileges
• Check if ports 11434 are available
• Verify sufficient disk space (5GB+)

Node.js Version Incompatible

Problem: Thought Ledger requires Node.js 18+ but you have an older version.

Solution:

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Verify installation
node --version  # Should show v18.x.x

Dependencies Won’t Install

Problem: npm install fails with errors.

Solutions:

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall dependencies
npm install

# If still failing, try with legacy peer deps
npm install --legacy-peer-deps

Runtime Issues

Thought Ledger Won’t Start

Problem: Application fails to start or shows errors.

Diagnostics:

# Check if Ollama is running
ollama list

# Check available ports
netstat -an | grep 3000
netstat -an | grep 11434

# Check system resources
free -h  # Memory
df -h    # Disk space

Common Solutions:

# Kill existing processes
pkill -f thought-ledger
pkill -f ollama

# Restart Ollama
ollama serve

# Start Thought Ledger
npm start

AI Model Not Responding

Problem: AI assistance is slow or doesn’t respond.

Diagnostics:

# Check Ollama status
ollama ps

# Test model directly
ollama run llama3.2:3b "Hello, test message"

# Check model is downloaded
ollama list

Solutions:

# Redownload model if corrupted
ollama pull llama3.2:3b

# Try a smaller model if memory is low
ollama pull llama3.2:1b

# Restart Ollama service
pkill -f ollama && ollama serve

Memory Issues

Problem: Application crashes or becomes unresponsive due to memory.

Solutions:

# Check memory usage
free -h
ps aux --sort=-%mem | head

# Use smaller AI model
ollama pull llama3.2:1b

# Update configuration to use smaller model
echo '{"ai":{"model":"llama3.2:1b"}}' > config.json

# Restart with increased Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" npm start

Database Issues

Database Won’t Initialize

Problem: SQLite database fails to create or open.

Diagnostics:

# Check data directory permissions
ls -la data/
ls -la data/decisions.db

# Test database creation
sqlite3 data/test.db "CREATE TABLE test (id INTEGER);"

Solutions:

# Create data directory if missing
mkdir -p data

# Fix permissions
chmod 755 data/

# Remove corrupted database and restart
rm data/decisions.db
npm start

Decision Search Not Working

Problem: Search functionality returns no results or errors.

Diagnostics:

# Check database content
sqlite3 data/decisions.db "SELECT COUNT(*) FROM decisions;"

# Check search index
sqlite3 data/decisions.db ".schema"

Solutions:

# Rebuild search index
npm run rebuild-index

# Clear cache and restart
rm -rf .cache/
npm start

Performance Issues

Slow AI Response Times

Problem: AI assistance takes too long to respond.

Solutions:

# Check system resources
htop  # CPU usage
free -h  # Memory usage

# Optimize for your hardware:
# 8GB RAM or less:
ollama pull llama3.2:1b

# 16GB RAM:
ollama pull llama3.2:3b

# 32GB+ RAM:
ollama pull llama3.2:8b

Interface Lag or Freezing

Problem: Web interface becomes slow or unresponsive.

Diagnostics:

# Check browser console for errors
# Open developer tools (F12) and check Console tab

# Check network requests
# Network tab in developer tools

Solutions:

# Clear browser cache and cookies
# Try a different browser

# Restart application
pkill -f thought-ledger
npm start

Configuration Issues

Settings Not Saving

Problem: Configuration changes don’t persist after restart.

Solutions:

# Check config file permissions
ls -la config.json

# Ensure writable permissions
chmod 644 config.json

# Verify config format
cat config.json | python3 -m json.tool

Model Selection Not Working

Problem: Can’t switch between AI models.

Diagnostics:

# Check available models
ollama list

# Check current configuration
cat config.json | grep model

Solutions:

# Update configuration manually
nano config.json

# Example configuration:
{
  "ai": {
    "model": "llama3.2:3b",
    "ollama_url": "http://localhost:11434"
  }
}

# Restart application
npm start

Network Issues

Port Conflicts

Problem: Ports 3000 or 11434 are already in use.

Diagnostics:

# Check what's using the ports
lsof -i :3000
lsof -i :11434

Solutions:

# Kill conflicting processes
sudo kill -9 <PID>

# Or use different ports
PORT=3001 npm start

Ollama Connection Failed

Problem: Thought Ledger can’t connect to Ollama service.

Diagnostics:

# Test Ollama directly
curl http://localhost:11434/api/tags

# Check if Ollama is running
ps aux | grep ollama

Solutions:

# Restart Ollama
pkill -f ollama
ollama serve

# Check firewall settings
# Ensure port 11434 is not blocked

Data Recovery

Lost Decision Data

Problem: Decision history disappeared or corrupted.

Solutions:

# Check for database backups
ls -la data/*.db.*
ls -la backups/

# Restore from backup if available
cp backups/decisions.db.backup data/decisions.db

# Export what you can recover
npm run export-data

Corrupted Database

Problem: Database file is corrupted and won’t open.

Solutions:

# Try database repair
sqlite3 data/decisions.db ".recover" | sqlite3 data/decisions_repaired.db

# If repair fails, start fresh (data loss warning!)
mv data/decisions.db data/decisions.db.corrupted
npm start

Getting Help

Debug Mode

Enable detailed logging for troubleshooting:

# Start with debug logging
DEBUG=thought-ledger:* npm start

# Check log files
tail -f logs/app.log
tail -f logs/error.log

System Information Report

Generate a system report for support:

# Create system report
npm run system-report

# This creates:
# - Hardware information
# - Software versions
# - Configuration details
# - Recent log entries

Community Support

• GitHub Issues: Report bugs
• Discussions: Ask questions
• Documentation: Check latest docs

Contact Support

If you continue to experience issues:

1. Generate system report: npm run system-report
2. Collect error logs: Check logs/error.log
3. Describe the issue: Include steps to reproduce
4. Contact: support@thought-ledger.com

---

Still having issues? Our community is active and ready to help. Don’t hesitate to reach out!