syntaxis/docs/troubleshooting.md

# syntaxis Troubleshooting Guide

Common issues and solutions.

## Installation Issues

### "Command not found" after installation

**Problem**: Binaries don't appear in PATH

**Solutions**:
```bash
# 1. Verify binaries were installed
ls -l ~/.local/bin/syntaxis-*

# 2. Check PATH includes installation directory
echo $PATH | grep .local/bin

# 3. If not found, add to PATH manually
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 4. Verify command works
which syntaxis-cli
syntaxis-cli --version
```

### "Permission denied" running binaries

**Problem**: Binaries exist but can't execute

**Solutions**:
```bash
# Make binaries executable
chmod +x ~/.local/bin/syntaxis-*

# Verify permissions
ls -l ~/.local/bin/syntaxis-* | head -1
# Should show: -rwxr-xr-x (755)

# Try running again
syntaxis-cli --version
```

### Installer script fails with "No such file or directory"

**Problem**: Installer can't find dependencies or directories

**Solutions**:
```bash
# Ensure you're in correct directory
pwd  # Should show: .../syntaxis-v0.1.0-...

# Check installer exists
ls -la install.sh

# Make it executable
chmod +x install.sh

# Run with explicit shell
bash install.sh --prefix ~/.local

# For NuShell version
nu install.nu --prefix ~/.local
```

### "Directory permission denied"

**Problem**: Can't write to installation directory

**Solutions**:
```bash
# Choose writable directory
./install.sh --prefix ~/syntaxis-install

# Or use sudo (not recommended)
sudo ./install.sh --prefix /usr/local

# Check directory permissions
ls -ld ~/.local
# Should show write permission (w) for user
```

## Configuration Issues

### Configuration files not found

**Problem**: `~/.config/syntaxis/` doesn't exist or is empty

**Solutions**:
```bash
# Create config directory
mkdir -p ~/.config/syntaxis

# Copy templates from bundle
cd syntaxis-v0.1.0-*
cp configs/*.toml ~/.config/syntaxis/

# Or use setup script
./setup-config.sh --interactive

# Verify files exist
ls ~/.config/syntaxis/
```

### "Invalid TOML" error

**Problem**: Configuration file has syntax errors

**Solutions**:
```bash
# Check file for syntax errors
cat ~/.config/syntaxis/syntaxis-cli.toml

# Look for common issues:
# - Missing quotes around values
# - Mismatched brackets
# - Invalid characters

# Restore from backup
cp ~/.config/syntaxis/syntaxis-cli.toml.backup \
   ~/.config/syntaxis/syntaxis-cli.toml

# Or copy from bundle again
cp configs/syntaxis-cli.toml ~/.config/syntaxis/

# Edit carefully with proper editor
nano ~/.config/syntaxis/syntaxis-cli.toml
```

### Configuration not being applied

**Problem**: Changes to config files don't take effect

**Solutions**:
```bash
# Restart the application
pkill syntaxis-api
pkill syntaxis-cli
pkill syntaxis-tui

# Wait a moment and restart
sleep 2
syntaxis-api &

# Explicitly set config directory
export SYNTAXIS_CONFIG_DIR=~/.config/syntaxis
syntaxis-api

# Check which config is being loaded (debug mode)
RUST_LOG=debug syntaxis-api 2>&1 | grep config | head -10
```

## Database Issues

### "Database locked" error

**Problem**: SQLite database is locked by another process

**Solutions**:
```bash
# Check what's using the database
lsof ~/.local/share/syntaxis/syntaxis.db

# Kill blocking processes
pkill syntaxis-api
pkill syntaxis-cli
pkill syntaxis-tui

# Wait for WAL cleanup
sleep 5

# Try again
syntaxis-api
```

### Database migration fails

**Problem**: Database schema migration fails on startup

**Solutions**:
```bash
# Check database file exists
ls -la ~/.local/share/syntaxis/syntaxis.db

# Backup before recovery
cp ~/.local/share/syntaxis/syntaxis.db \
   ~/.local/share/syntaxis/syntaxis.db.backup

# Delete and let it recreate
rm ~/.local/share/syntaxis/syntaxis.db

# Restart to rebuild
syntaxis-api

# If using SurrealDB
rm -rf ~/.local/share/syntaxis/surrealdb/
syntaxis-api
```

### "Connection refused" to database

**Problem**: Can't connect to SurrealDB or remote database

**Solutions**:
```bash
# Check if SurrealDB server is running
netstat -an | grep 8000

# Start SurrealDB if not running
surreal start --bind 127.0.0.1:8000 \
  file:///tmp/syntaxis.db &

# Verify connection
curl http://localhost:8000

# Check config points to right URL
cat ~/.config/syntaxis/database-surrealdb.toml | grep url

# Check firewall isn't blocking
sudo iptables -L | grep 8000
```

## API Server Issues

### API server won't start

**Problem**: `syntaxis-api` exits immediately or hangs

**Solutions**:
```bash
# Check for port conflicts
lsof -i :3000

# If port 3000 in use, kill process or use different port
export SYNTAXIS_API_PORT=8000
syntaxis-api

# Check logs for errors
syntaxis-api 2>&1 | head -20

# With verbose logging
RUST_LOG=debug syntaxis-api 2>&1 | head -50

# Check config file
cat ~/.config/syntaxis/syntaxis-api.toml | head -20
```

### "Address already in use"

**Problem**: Port 3000 is already in use

**Solutions**:
```bash
# Find what's using port 3000
lsof -i :3000
# or
netstat -an | grep 3000

# Kill the process
kill -9 <PID>

# Or use different port
SYNTAXIS_API_PORT=8080 syntaxis-api

# Update config for new port
sed -i 's/port = 3000/port = 8080/' \
  ~/.config/syntaxis/syntaxis-api.toml
```

### API server crashes with segmentation fault

**Problem**: `syntaxis-api` crashes with "Segmentation fault"

**Solutions**:
```bash
# This is usually a database issue
# Try backing up and recreating database
cp ~/.local/share/syntaxis/syntaxis.db \
   ~/.local/share/syntaxis/syntaxis.db.broken

rm ~/.local/share/syntaxis/syntaxis.db

# Restart server
syntaxis-api

# If still fails, try SurrealDB instead
sed -i 's/backend = "sqlite"/backend = "surrealdb"/' \
  ~/.config/syntaxis/syntaxis-api.toml

# Start SurrealDB
surreal start --bind 127.0.0.1:8000 memory &

# Try again
syntaxis-api
```

## TUI Issues

### TUI displays incorrectly / garbled output

**Problem**: Terminal rendering issues in `syntaxis-tui`

**Solutions**:
```bash
# Ensure terminal supports 256 colors
echo $TERM

# Set proper terminal type
export TERM=xterm-256color
syntaxis-tui

# Or use simpler terminal
TERM=screen syntaxis-tui

# Clear terminal and try again
clear
syntaxis-tui

# Check terminal size is adequate
stty size  # Should be at least 80x24
```

### TUI keyboard shortcuts don't work

**Problem**: vim-style keybindings not responding

**Solutions**:
```bash
# Check keybindings config
cat ~/.config/syntaxis/syntaxis-tui.toml | grep keybindings -A 10

# Check terminal isn't consuming keys
# Try in different terminal (iTerm, Gnome Terminal, etc.)

# Reset keybindings to defaults
# Edit syntaxis-tui.toml and restore from backup
cp configs/syntaxis-tui.toml ~/.config/syntaxis/

# Check for conflicting terminal keybindings
# Try raw mode:
stty raw
syntaxis-tui
stty -raw
```

### TUI crashes with "Panicked at index out of bounds"

**Problem**: TUI crashes with panic error

**Solutions**:
```bash
# This usually means corrupted data
# Backup config and reset
cp ~/.config/syntaxis/syntaxis-tui.toml \
   ~/.config/syntaxis/syntaxis-tui.toml.broken

cp configs/syntaxis-tui.toml ~/.config/syntaxis/

# Try again
syntaxis-tui

# Check terminal is large enough
stty size  # Should be >80x24
```

## Performance Issues

### Application runs slowly

**Problem**: syntaxis commands are slow

**Solutions**:
```bash
# Check database file size
du -sh ~/.local/share/syntaxis/syntaxis.db

# Optimize SQLite if large
sqlite3 ~/.local/share/syntaxis/syntaxis.db "VACUUM;"

# Enable WAL mode for concurrent access
sqlite3 ~/.local/share/syntaxis/syntaxis.db "PRAGMA journal_mode=WAL;"

# Check system resources
top -p $(pgrep syntaxis-api)

# Monitor disk I/O
iostat -x 1

# Try with fewer projects/tasks
syntaxis-cli project list | wc -l
```

### API server is unresponsive

**Problem**: API requests hang or timeout

**Solutions**:
```bash
# Check server is running
curl http://localhost:3000/health

# Check connection pool isn't exhausted
RUST_LOG=debug syntaxis-api 2>&1 | grep pool

# Increase connection pool
sed -i 's/pool_size = 5/pool_size = 20/' \
  ~/.config/syntaxis/syntaxis-api.toml

pkill syntaxis-api
sleep 2
syntaxis-api &

# Check for slow queries
sqlite3 ~/.local/share/syntaxis/syntaxis.db "SELECT sqlite_version();"
```

## Data Issues

### Lost projects or tasks

**Problem**: Projects disappeared or data is missing

**Solutions**:
```bash
# Check if database still has data
sqlite3 ~/.local/share/syntaxis/syntaxis.db ".tables"

# Count projects
sqlite3 ~/.local/share/syntaxis/syntaxis.db \
  "SELECT COUNT(*) FROM projects;"

# Restore from backup if available
ls -la ~/.local/share/syntaxis/*.backup

# If backup exists
cp ~/.local/share/syntaxis/syntaxis.db.backup \
   ~/.local/share/syntaxis/syntaxis.db
```

### Corrupted database

**Problem**: Database errors like "database disk image is malformed"

**Solutions**:
```bash
# Check integrity
sqlite3 ~/.local/share/syntaxis/syntaxis.db "PRAGMA integrity_check;"

# If corrupted, recover if possible
sqlite3 ~/.local/share/syntaxis/syntaxis.db ".recover" | \
  sqlite3 ~/.local/share/syntaxis/syntaxis.db.recovered

# Use recovered version if good
mv ~/.local/share/syntaxis/syntaxis.db \
   ~/.local/share/syntaxis/syntaxis.db.broken
mv ~/.local/share/syntaxis/syntaxis.db.recovered \
   ~/.local/share/syntaxis/syntaxis.db

# Otherwise, delete and rebuild
rm ~/.local/share/syntaxis/syntaxis.db
syntaxis-api  # Rebuilds clean database
```

## Getting Help

If issues persist:

1. **Check logs**:
   ```bash
   RUST_LOG=debug syntaxis-api 2>&1 | tee /tmp/syntaxis-debug.log
   ```

2. **Check config**:
   ```bash
   cat ~/.config/syntaxis/*.toml
   ```

3. **Report issue** with:
   - OS and version
   - syntaxis version
   - Steps to reproduce
   - Error messages/logs
   - Go to [syntaxis repository](https://github.com/syntaxis/syntaxis/issues)

4. **Contact support**:
   - Review project documentation
   - Check bundle `QUICK_START.md`
   - See `CONFIG_GUIDE.md` for configuration help