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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

   RUST_LOG=debug syntaxis-api 2>&1 | tee /tmp/syntaxis-debug.log
   

2. Check config:

   cat ~/.config/syntaxis/*.toml
   

3. Report issue with:

   • OS and version
   • syntaxis version
   • Steps to reproduce
   • Error messages/logs
   • Go to syntaxis repository

4. Contact support:

   • Review project documentation
   • Check bundle QUICK_START.md
   • See CONFIG_GUIDE.md for configuration help