Troubleshooting

Solutions to common issues you may encounter with Nexgent.

Startup Issues

Backend won't start

Error: DATABASE_URL is not defined

# Solution: Ensure .env file exists and is properly configured
cp .env.example .env
# Edit .env with your values

Error: Can't reach database server

# Check PostgreSQL is running
docker ps | grep postgres
 
# Verify connection string
psql $DATABASE_URL -c "SELECT 1"

Error: Redis connection refused

# Check Redis is running
docker ps | grep redis
 
# Test connection
redis-cli -h localhost -p 6379 ping

Frontend won't start

Error: NEXTAUTH_SECRET must be at least 32 characters

# Generate a proper secret
pnpm --filter frontend generate-secret
# Copy output to .env.local

Error: Invalid NEXTAUTH_URL

# Ensure URL matches your setup
NEXTAUTH_URL=http://localhost:3000  # Development
NEXTAUTH_URL=https://yourdomain.com  # Production

Port already in use

# Kill process on port 4000 (backend)
npx kill-port 4000
 
# Kill process on port 3000 (frontend)
npx kill-port 3000
 
# Or use the cleanup script
pnpm cleanup:ports:force

Database Issues

Migrations failing

Error: Migration failed to apply cleanly

# Reset database (WARNING: deletes all data)
pnpm --filter backend db:push --force-reset
 
# Or create fresh migration
pnpm --filter backend db:migrate

Error: Prisma client out of sync

# Regenerate Prisma client
pnpm --filter backend db:generate

Can't connect to database

1. Check PostgreSQL is running
2. Verify DATABASE_URL format:

   postgresql://USER:PASSWORD@HOST:PORT/DATABASE
3. Check firewall/network access
4. Verify credentials are correct

Data not persisting

Check that you're using the correct database:

# Verify DATABASE_URL points to expected database
echo $DATABASE_URL
 
# Check database exists
psql -h localhost -U postgres -l

Redis Issues

Cache not working

Symptoms: Slow queries, stale data

# Check Redis connection
pnpm --filter backend cache:status
 
# Reset cache
pnpm --filter backend cache:reset
 
# Warm cache
pnpm --filter backend cache:warmup

Redis connection timeout

# Check if Redis is reachable
redis-cli -h $REDIS_HOST -p $REDIS_PORT ping
 
# Check for max connections
redis-cli INFO clients

Out of memory

# Check Redis memory usage
redis-cli INFO memory
 
# Set max memory policy (in redis.conf)
maxmemory 256mb
maxmemory-policy allkeys-lru

Trading Issues

Agent not executing trades

Checklist:

Debug steps:

# Check agent status via API
curl http://localhost:4000/api/v1/agents \
  -H "Authorization: Bearer <token>"
 
# Check wallet is loaded (look for startup log)
# "Loaded wallet: ABC123..."

Balance showing 0 or incorrect

# 1. Verify on-chain balance
solana balance <wallet-address> --url <rpc-url>
 
# 2. Check wallet is configured
grep WALLET_ .env
 
# 3. Reset balance cache
pnpm --filter backend cache:reset

Trades failing with slippage error

Error: Slippage tolerance exceeded

Solutions:

1. Increase slippage in trade config
2. Reduce trade size
3. Avoid low-liquidity tokens
4. Try during lower-traffic periods

Stop loss not triggering

Checklist:

1. Stop loss is enabled in agent config
2. Price feed is working (check Pyth connection)
3. Position exists and is active
4. Price has actually crossed threshold

# Check price service status
curl http://localhost:4000/api/v1/prices/sol-usd

DCA not triggering

Checklist:

1. DCA is enabled in agent config
2. Position hasn't reached max DCA level
3. Agent has sufficient balance for DCA buy
4. Price has crossed DCA threshold

API Issues

401 Unauthorized

403 Forbidden

Error: API key missing required scope

Your API key doesn't have permission for this action. Generate a new key with the required scope (read, write, signals).

429 Too Many Requests

You've reached a limit. Wait and retry:

# Response includes retry time
{
  "error": "Too many requests",
  "retryAfter": 45
}

Solutions:

• Implement exponential backoff
• Reduce request frequency
• Use API key for higher limits

500 Internal Server Error

Check backend logs for details:

# View logs
docker logs nexgent-backend
 
# Or if running directly
# Check terminal output

WebSocket Issues

Dashboard not updating in real-time

1. Check WebSocket connection - Browser console shows connection status
2. Check backend is running - WebSocket server starts with backend
3. Check firewall - Port 4000 must be accessible
4. Check proxy config - Nginx/reverse proxy must support WebSocket

Nginx WebSocket config:

location /ws {
    proxy_pass http://localhost:4000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

WebSocket disconnecting frequently

Possible causes:

• Network instability
• Proxy timeout settings
• Server resource constraints

Solutions:

• Increase proxy timeouts
• Check server resources
• Implement reconnection logic (built into dashboard)

Price Feed Issues

SOL/USD price not updating

Check Pyth connection:

# Test Pyth SSE endpoint
curl "https://hermes.pyth.network/v2/updates/price/stream?ids[]=0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d"

Common causes:

• Network firewall blocking SSE
• Pyth service temporarily unavailable
• Invalid price feed ID

Token prices not loading

Check price provider:

# Test Jupiter price API
curl "https://lite-api.jup.ag/price/v2?ids=<token-address>"
 
# Or DexScreener
curl "https://api.dexscreener.com/tokens/v1/solana/<token-address>"

If Jupiter fails:

• Check JUPITER_API_KEY is valid
• Try switching to DexScreener: PRICE_PROVIDER=dexscreener

Performance Issues

Slow response times

1. Check database queries - Enable query logging
2. Check Redis connection - Ensure caching is working
3. Check memory usage - May need more RAM
4. Check CPU usage - May need more cores

# Monitor resource usage
docker stats

High memory usage

# Check Node.js heap
node --max-old-space-size=2048 dist/index.js
 
# Check for memory leaks in logs

Database connection exhaustion

# Check active connections
psql -c "SELECT count(*) FROM pg_stat_activity;"
 
# Increase pool size in DATABASE_URL or Prisma config

Common Error Messages

Getting Help

If you can't resolve your issue:

1. Search existing issues - GitHub Issues (opens in a new tab)
2. Check discussions - GitHub Discussions (opens in a new tab)
3. Collect information:
   • Error messages (full stack trace)
   • Environment (OS, Node version)
   • Steps to reproduce
   • Relevant config (redact secrets!)
4. Open a new issue with the information above