Troubleshooting

Common issues and their solutions

Hub Issues

Server won't start

Error: EADDRINUSE: address already in use :::51842

Cause: Another process is using port 51842.

Solution:

bash 
# Find the process using the port
lsof -i :51842

# Kill it
kill -9 <PID>

# Or use a different port
PORT=3000 pnpm dev

Database connection failed

Error: ECONNREFUSED connecting to PostgreSQL

Cause: PostgreSQL is not running or connection string is wrong.

Solution:

bash 
# Check PostgreSQL status
sudo systemctl status postgresql

# Start if not running
sudo systemctl start postgresql

# Or use embedded SQLite (edit .env)
# Comment out DATABASE_URL to use SQLite

Ollama not connecting

Warning: Ollama adapter failed to connect

Cause: Ollama is not running or using wrong URL.

Solution:

bash 
# Check Ollama status
curl http://localhost:11434/api/tags

# Start Ollama
ollama serve

# If using Docker, ensure host networking
docker run -d --network host ollama/ollama

Spoke Issues

Device shows offline

Cause: Telemetry is not being sent to the hub.

Solution:

bash 
# Check spoke service status
sudo systemctl status seaclip-spoke

# View logs
sudo journalctl -u seaclip-spoke -f

# Test hub connectivity
curl http://<hub-ip>:51842/api/health

# Restart spoke
sudo systemctl restart seaclip-spoke

Registration failed

Error: Device registration failed: 401 Unauthorized

Cause: Hub is in authenticated mode and requires a token.

Solution:

bash 
# Option 1: Switch hub to local_trusted mode
# Edit .env on hub:
SEACLIP_DEPLOYMENT_MODE=local_trusted

# Option 2: Get an API token from hub admin
# Then register with token:
pnpm spoke register --token <api-token>

Agent ping timeout

Cause: Agent process is not running or network issue.

Solution:

bash 
# Check if agent process is running
ps aux | grep seaclip

# Check network from hub to spoke
ping <spoke-ip>
nc -zv <spoke-ip> 51843

# Check firewall on spoke
sudo ufw status
sudo ufw allow 51843

SpacetimeDB Issues

Connection shows "Connecting..."

Cause: SpacetimeDB module not published or network issue.

Solution:

bash 
# Check if module is published
spacetime logs seaclip-realtime

# Republish if needed
cd /opt/seaclip/spacetimedb
spacetime build
spacetime publish seaclip-realtime

# Regenerate TypeScript bindings
spacetime generate seaclip-realtime --lang typescript \
  --out-dir ../ui/src/lib/spacetimedb/generated

Data not syncing

Cause: Reducers not being called or connection not ready.

Solution:

  1. Open browser console (F12)
  2. Look for [SpacetimeDB] log messages
  3. Check for errors like "Not connected" or "Reducer failed"
javascript — Browser Console 
// Check connection status
localStorage.getItem('spacetimedb_token')

// Clear token and reconnect
localStorage.removeItem('spacetimedb_token')
location.reload()

Build Issues

TypeScript errors

Error: Cannot find module '@seaclip/shared'

Solution:

bash 
# Rebuild all packages
pnpm build

# Or rebuild specific package
pnpm --filter @seaclip/shared build

# Clear cache and reinstall
rm -rf node_modules
pnpm install

Rust/SpacetimeDB build fails

Error: wasm32-unknown-unknown target not found

Solution:

bash 
# Add WASM target
rustup target add wasm32-unknown-unknown

# Update Rust
rustup update

# Rebuild
cd /opt/seaclip/spacetimedb
spacetime build

Performance Issues

Dashboard is slow

Cause: Too many devices or high telemetry frequency.

Solution:

High memory usage

Cause: Telemetry data accumulating in database.

Solution:

bash 
# Clean old telemetry (keep last 7 days)
pnpm cli db:cleanup --telemetry-days 7

# Or via SQL (PostgreSQL)
DELETE FROM device_telemetry 
WHERE timestamp < NOW() - INTERVAL '7 days';

Getting Help

Collect diagnostic info

bash 
# Run full diagnostics
pnpm cli doctor --verbose > diagnostics.txt

# Include system info
uname -a >> diagnostics.txt
node -v >> diagnostics.txt
pnpm -v >> diagnostics.txt

Report an issue

Open an issue on GitHub with:

Open GitHub Issue →