Skip to content

Troubleshooting

Jump to bottom
cyclonite69 edited this page Feb 7, 2026 · 1 revision

Troubleshooting

Common issues and solutions for ShadowCheck

Database Connection Errors

Problem: Connection Refused

Symptoms:

  • ECONNREFUSED error
  • Cannot connect to PostgreSQL

Solution:

# Verify Docker PostgreSQL is running
docker ps | grep shadowcheck_postgres

# Or check local PostgreSQL
sudo systemctl status postgresql

# Test connection
docker exec shadowcheck_postgres psql -U shadowcheck_user -d shadowcheck_db

Problem: Password Authentication Failed

Solution:

# Reset password in PostgreSQL
sudo -u postgres psql
postgres=# ALTER USER shadowcheck_user WITH PASSWORD 'new_password';

# Update keyring
node scripts/set-secret.js db_password "new_password"

Map is Blank

Symptoms:

  • Map area is empty/gray
  • No map tiles loading

Solutions:

  1. Verify mapbox_token is set in keyring
  2. Check browser console for Mapbox GL errors
  3. Ensure token has correct permissions

Dashboard Shows Zeros

Symptoms:

  • All metrics showing 0
  • No network data displayed

Solution:

-- Check data exists
SELECT COUNT(*) FROM public.networks;

-- Verify home location
SELECT * FROM app.location_markers WHERE name = 'home';

-- Check materialized views are refreshed
REFRESH MATERIALIZED VIEW analytics_summary_mv;

High Memory Usage

Symptoms:

  • JavaScript heap out of memory error
  • Server crashes with large datasets

Solution:

# Increase Node.js heap size
NODE_OPTIONS="--max-old-space-size=4096" npm start

Port Already in Use

Symptoms:

  • EADDRINUSE: address already in use :::3001

Solution:

# Find process using port
lsof -i :3001

# Kill process
kill -9 <PID>

# Or change PORT in .env
PORT=3002

Migration Errors

Problem: Relation Already Exists

Solution (Development Only):

# Drop and recreate schema
psql -U shadowcheck_user -d shadowcheck_db -c "DROP SCHEMA app CASCADE; CREATE SCHEMA app;"

# Re-run migrations
psql -U shadowcheck_admin -d shadowcheck_db -f sql/migrations/00_init_schema.sql

Slow Queries

Symptoms:

  • API requests taking >5 seconds
  • Dashboard loading slowly

Solution:

-- Check slow queries
SELECT query, mean_exec_time, calls
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

-- Analyze and vacuum
ANALYZE;
VACUUM ANALYZE;

Access Denied on Admin Page

Symptoms:

  • "Access Denied" message on Admin page
  • Cannot perform admin operations

Solution:

  1. Verify db_admin_password secret is configured
  2. Check user has admin role in database
  3. Ensure API key is set for protected endpoints

Debugging Steps

Enable Debug Logging

# Set environment variable
DEBUG=shadowcheck:* npm start

# Or in .env
LOG_LEVEL=debug

Check Server Logs

# View Docker logs
docker-compose logs -f api

# Check structured logs
cat logs/combined.log

Related Documentation

Clone this wiki locally