Troubleshooting

Common issues and solutions when running Lattice.

Quick Diagnostics

Run the built-in diagnostics tool:

ada doctor

This checks:

• Daemon status
• Provider connectivity
• Configuration validity
• System requirements

Daemon Issues

Daemon Not Running

Symptom: Commands fail with "connection refused" or "daemon not running"

Solution:

# Check daemon status
lattice-ctl ping

# Start the daemon
lattice-ctl daemon start

# Or start the service
lattice-ctl service start

Daemon Won't Start

Symptom: lattice-ctl daemon start fails

Check the logs:

# macOS
cat ~/Library/Logs/lattice/daemon.log

# Linux
journalctl -u lattice -n 50

Common causes:

1. Port already in use – Another process is using the socket
2. Permission denied – Check file permissions on config directory
3. Invalid configuration – Validate config:
   bash

   lattice-ctl config validate
   

Daemon Crashes

Symptom: Daemon starts but crashes shortly after

Solution:

1. Check logs for error messages
2. Reset configuration:
   bash

   lattice-ctl config reset -f
   

3. Restart:
   bash

   lattice-ctl daemon start
   

Provider Issues

Provider Connection Failed

Symptom: ada chat fails with connection errors

Test the provider:

ada config provider test

Common causes:

1. Invalid API key – Check your API key:

   bash

   ada config provider show <provider> --show-secrets
   

2. Network issues – Check internet connection for cloud providers

3. Ollama not running – For local models:

   bash

   # Start Ollama
   ollama serve
   
   # Test connection
   ada config provider test ollama
   

Wrong Model

Symptom: Getting unexpected model responses

Check active provider and model:

ada config provider list
ada config provider show <active_provider>

Switch models:

ada config provider set <provider> --model <model_name>

Rate Limiting

Symptom: Requests fail with rate limit errors

Solutions:

1. Wait and retry
2. Switch to a different provider
3. Use a local model (Ollama) for unlimited requests

Agent Issues

Agent Won't Start

Symptom: ada agents start fails

Check:

1. Daemon is running:

   bash

   lattice-ctl ping
   

2. Provider is configured:

   bash

   ada config provider list
   

3. Active provider works:

   bash

   ada config provider test
   

Agent Stuck

Symptom: Agent shows as "running" but not making progress

Solutions:

1. Check agent status:

   bash

   ada agents status <agent_id>
   

2. Force stop and restart:

   bash

   ada agents stop <agent_id> --force
   ada agents start "your task"
   

Can't Find Agent

Symptom: Agent ID not found

List all agents:

ada agents list --verbose

Agents may have completed or been stopped. Check if it's in a different workspace:

ada agents list --workspace <workspace_id>

Session Issues

Session Not Saving

Symptom: Chat history not persisting

Check daemon is running:

lattice-ctl ping

Sessions are stored in the daemon's SQLite database. If the daemon isn't running, sessions won't persist.

Can't Resume Session

Symptom: ada sessions resume fails

List available sessions:

ada sessions list

Check session exists:

ada sessions info <session_id>

Configuration Issues

Invalid Configuration

Symptom: Commands fail with config errors

Validate configuration:

lattice-ctl config validate

Reset to defaults:

lattice-ctl config reset -f

Config Changes Not Applied

Symptom: Changed config but behavior unchanged

Apply changes:

lattice-ctl config set <key> <value> --apply

Or restart the daemon:

lattice-ctl daemon stop
lattice-ctl daemon start

Installation Issues

Command Not Found

Symptom: lattice-ctl: command not found or ada: command not found

Solutions:

1. Reinstall:

   bash

   curl -fsSL https://uselovelace.com/lattice/install.sh | sh
   

2. Check PATH:

   bash

   echo $PATH
   which lattice-ctl
   which ada
   

3. Reload shell:

   bash

   source ~/.bashrc  # or ~/.zshrc
   

Permission Denied

Symptom: Commands fail with permission errors

Solutions:

1. Fix ownership:

   bash

   # macOS/Linux
   sudo chown -R $USER ~/.lovelace
   

2. Check service permissions:

   bash

   lattice-ctl service status
   

Network Issues

P2P Connection Failed

Symptom: Can't connect to other devices in mesh

Check:

1. Both devices running Lattice daemon
2. Network allows peer-to-peer connections
3. Firewall not blocking connections

Cloud Sync Failed

Symptom: Hybrid mode sync not working

Check authentication:

ada auth status

Re-authenticate:

ada auth logout
ada auth login

Performance Issues

Slow Response Times

Possible causes:

1. Cloud provider latency – Try a local model:

   bash

   ada config provider activate ollama
   

2. Large context – Start a fresh session:

   bash

   ada chat
   

3. System resources – Check CPU/memory usage

High Memory Usage

Solutions:

1. Stop unused agents:

   bash

   ada agents list
   ada agents stop <agent_id>
   

2. Clear old sessions:

   bash

   ada sessions list
   ada sessions delete <old_session_id>
   

3. Restart daemon:

   bash

   lattice-ctl daemon stop
   lattice-ctl daemon start
   

Getting Help

Collect Diagnostics

ada doctor > diagnostics.txt
lattice-ctl status >> diagnostics.txt
lattice-ctl config show >> diagnostics.txt

Check Logs

macOS:

cat ~/Library/Logs/lattice/daemon.log

Linux:

journalctl -u lattice -n 100

Windows:

Get-EventLog -LogName System -Source "lattice" -Newest 50

Report Issues

If you're still stuck, collect the diagnostics above and report the issue with:

1. What you were trying to do
2. The exact error message
3. Output of ada doctor
4. Relevant log entries