Troubleshooting

Common issues, solutions, and debugging tips for the DashClicks microservices architecture.

Quick Diagnostics

Service Health Check

Verify core services are running and healthy:

# Check API Router (main gateway)
curl http://localhost:5001/status

# Check Internal API
curl http://localhost:5002/status

# Check External Integrations API
curl http://localhost:5003/status

# Check Dashboard Gateway
curl http://localhost:5000/status

# Check Socket Services
curl http://localhost:6001/status  # Conversation Socket
curl http://localhost:4000/status  # General Socket

Expected Response:

{
  "status": "ok"
}

Problem Indicators:

• No response - Service isn't running
• Error response - Service has configuration or database issues
• Connection refused - Port not available or service crashed

Installation & Setup Issues

Initial Setup Problems

Error:

pnpm run build fails with missing dependencies

Solutions:

1. Check .env file exists:

   ls -la .env

2. Copy from sample template:

   cp .env.sample .env

3. Ask fellow developers for missing values:

   • Contact team members for actual MongoDB connection strings
   • Request JWT secrets and API keys for development environment
   • Get third-party integration credentials (Stripe, Twilio, etc.)

4. Verify file contents:

   cat .env
   # Should show your MongoDB URL, JWT secrets, and API keys

5. Test environment loading:

   node -e "require('dotenv').config(); console.log(process.env.MONGO_DB_URL ? 'Environment loaded' : 'Environment not loaded')"

Import/Module Errors

Error:

Cannot find module './services/something'

Causes & Solutions:

1. Use CommonJS require without .js extension:

   // ✅ Correct for DashClicks
   const { Service } = require('./services/myService');
   const userModel = require('./models/user');
   const authUtils = require('./utilities/auth');

2. Check shared files are copied:

   # Verify models and utilities exist in services
   ls -la internal/api/v1/models/
   ls -la external/Integrations/utilities/
   ls -la conversation-socket/models/

3. Common folder files not copied:

   # Check if conversation files were copied from common/
   ls -la internal/api/v1/conversation-v2/services/
   ls -la internal/api/v1/conversation-v2/constants/
   ls -la conversation-socket/src/services/
   ls -la conversation-socket/src/constants/

4. Run copySharedFiles for all shared content:

   # This copies from both /shared and /common folders
   pnpm run copySharedFiles

5. Edit files in correct locations:

   • Models/Utilities: Edit in /shared/ folder only
   • Conversation services: Edit in /common/conversations/ folder only
   • Never edit copied files in service folders - they are Git-ignored

6. Node.js version compatibility:

   node --version  # Should be 18+

Port Already in Use

Error:

Error: listen EADDRINUSE: address already in use :::5001

Solutions:

1. Find what's using the port:

   lsof -i :5001
   # or
   netstat -tulpn | grep :5001

2. Kill the process:

   kill -9 <PID>

3. Check if another DashClicks service is running:

   # Check all DashClicks service ports
   lsof -i :5000 -i :5001 -i :5002 -i :5003 -i :4000 -i :6001 -i :6002 -i :5008

4. Stop all services and restart through VS Code debugger

Runtime Issues

Database Connection Problems

Error:

MongooseError: Operation `users.findOne()` buffering timed out after 10000ms

Solutions:

1. Check MongoDB connection string:

   # Verify MongoDB URL in .env
   echo $MONGO_DB_URL

2. Test MongoDB connectivity:

   # Using MongoDB shell
   mongosh "your_mongodb_connection_string"

3. Check network access:

   • Ensure MongoDB Atlas IP whitelist includes your IP
   • Verify firewall settings allow MongoDB traffic

4. Restart services with fresh connection:

   • Stop all services in VS Code debugger
   • Restart "Start All Services" configuration

Shared Files Out of Sync

Error:

Cannot find module './models/user' or './utilities/auth'

Solutions:

1. Copy shared files:

   pnpm run copySharedFiles

2. Verify shared files were copied:

   # Check if models exist in service folders
   ls -la internal/api/v1/models/
   ls -la external/Integrations/models/

3. Check for Git issues:

   # These folders should be Git-ignored
   git status | grep models/
   git status | grep utilities/

Third-Party API Issues

Error:

Stripe API Error: 401 Unauthorized

Solutions:

1. Verify API keys in .env:

   # Check Stripe keys (test vs live)
   echo $STRIPE_SECRET_KEY | head -c 20

2. Test API connectivity:

   # Test Stripe API directly
   curl -H "Authorization: Bearer $STRIPE_SECRET_KEY" \
        https://api.stripe.com/v1/customers/limit=1

3. Check webhook endpoints:

   • Ensure ngrok is running for local development
   • Verify webhook URLs in third-party dashboards

4. Review integration logs:

   • Check External API service logs in VS Code debugger console

Service Communication Issues

Service Not Responding

Symptoms:

• Services can't communicate with each other
• API Router returns 503 Service Unavailable
• Socket connections failing

Solutions:

1. Check service startup order:

   • Always start API Router (5001) first
   • Then start Internal API (5002) and External API (5003)
   • Start socket services after core APIs

2. Verify service URLs in .env:

   # Check service communication URLs
   echo $INTERNAL_BASE_URL
   echo $EXTERNAL_BASE_URL
   echo $SOCKET_API
   echo $CONVERSATION_SOCKET

3. Test inter-service connectivity:

   # From API Router to Internal API
   curl http://localhost:5002/status
   # From API Router to External API
   curl http://localhost:5003/status

Queue Manager Issues

Error:

Queue processing failed - Redis connection error

Solutions:

1. Check Redis connection:

   # Test Redis connectivity
   redis-cli ping

2. Verify Redis configuration:

   echo $REDIS_HOST
   echo $REDIS_PORT

3. Check queue flags:

   • Set queue flags to false in development to prevent background processing
   • Enable only necessary queues for testing

Socket Connection Problems

Symptoms:

• Real-time features not working
• Chat messages not delivering
• Live updates not appearing

Solutions:

1. Check socket services are running:

   curl http://localhost:4000/status   # General Socket
   curl http://localhost:6001/status  # Conversation Socket

2. Verify Redis for socket scaling:

   • Socket services require Redis for multi-instance communication
   • Check Redis connection in socket service logs

3. Test socket endpoints:

   • Use browser developer tools to check WebSocket connections
   • Look for CORS issues in network tab

Performance Issues

Memory Problems

Error:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Solutions:

1. Increase Node.js memory:

   export NODE_OPTIONS="--max-old-space-size=2048"
   pnpm start

2. Process documents in batches:

   • Move some documents temporarily
   • Process in smaller groups
   • Monitor memory usage

3. Check for memory leaks:

   # Monitor memory over time
   while true; do ps aux | grep node | grep -v grep; sleep 5; done

High CPU Usage

Symptoms:

• CPU constantly at 100%
• System becomes unresponsive

Solutions:

1. Limit concurrent processing:

   • Reduce batch sizes in document processing
   • Add delays between operations

2. Check for infinite loops:

   • Review logs for repeated errors
   • Restart API if needed

3. Profile the application:

   node --prof apps/api/src/index.ts

Network & Connectivity Issues

CORS Errors

Error in Browser:

Access to fetch at 'http://localhost:5001/v1/users' from origin 'http://localhost:3000' has been blocked by CORS policy

Solution: DashClicks services have CORS enabled by default. If you see this error:

1. Verify API Router is running:

   curl http://localhost:5001/status

2. Check Dashboard Gateway proxy:

   • Ensure Dashboard Gateway (port 5000) is properly proxying requests
   • Verify frontend is making requests through Dashboard Gateway

3. Check service-specific CORS:

   • Review CORS settings in individual services
   • Ensure proper headers are set for OPTIONS requests

Service Unreachable

Error:

curl: (7) Failed to connect to localhost port 5001: Connection refused

Solutions:

1. Verify services are running:

   # Check all DashClicks services
   ps aux | grep -E "node.*internal|node.*router|node.*dashboard"

2. Check VS Code debugger:

   • Use VS Code Debug panel to start services
   • Check debug console for startup errors

3. Test individual services:

   curl http://localhost:5001/status  # API Router
   curl http://localhost:5002/status  # Internal API
   curl http://localhost:5003/status  # External API

Development Issues

Auto-restart Not Working

Problem: Changes to code don't trigger service restart in VS Code debugger

Solutions:

1. Check VS Code debugger auto-restart:

   • Ensure debug configuration has "restart": true
   • Verify file watching is enabled in debug console

2. Manual service restart:

   • Stop debug session in VS Code
   • Start fresh debug session for affected service

3. Check file permissions:

   chmod -R 755 internal/api/v1/
   chmod -R 755 external/

Module Resolution Errors

Error:

Cannot find module '../models/user.js'

Solutions:

1. Check shared files were copied:

   # Verify models exist in service
   ls -la internal/api/v1/models/user.js
   ls -la external/Integrations/models/user.js

2. Run shared file copy:

   npm run copySharedFiles
   # or for development with symlinks
   npm run dev:build

3. Check require/import paths:

   • Ensure correct relative paths to copied shared files
   • Verify no circular dependencies between services

VS Code Debugger Issues

Services Won't Start in Debugger

Problem: VS Code debug configurations fail to launch services

Solutions:

1. Check launch.json configuration:

   # Verify .vscode/launch.json exists
   ls -la .vscode/launch.json

2. Verify Node.js path:

   • Ensure Node.js 18+ is installed and in PATH
   • Check VS Code is using correct Node.js version

3. Clear VS Code cache:

   • Close VS Code completely
   • Delete .vscode/.debug folder if exists
   • Reopen VS Code and try again

4. Check environment variables:

   • Ensure .env file is in root directory
   • Verify no syntax errors in .env file

Breakpoints Not Working

Problem: Debugger doesn't pause at breakpoints

Solutions:

1. Check source maps:

   • Ensure services are running in development mode
   • Verify NODE_ENV=development in debug configuration

2. Restart debugger:

   • Stop all running debug sessions
   • Start fresh debug session for specific service

3. Check file paths:

   • Ensure breakpoints are set in actual source files
   • Not in copied or generated files

Debugging Tips

Enable Debug Logging

Add more detailed logging to understand what's happening:

# In your .env file
DEBUG_MODE=true
NODE_ENV=development
LOG_LEVEL=debug

Service Health Check Script

Test all services systematically:

#!/bin/bash
# Create a debug script for DashClicks

echo "=== DashClicks Backend Debug Information ==="
echo "Date: $(date)"
echo ""

echo "=== Environment ==="
echo "Node version: $(node --version)"
echo "npm version: $(npm --version)"
echo "pnpm version: $(pnpm --version)"
echo ""

echo "=== Process Status ==="
ps aux | grep -E "node.*internal|node.*external|node.*router|node.*dashboard|node.*socket|node.*queue|node.*notification" | grep -v grep
echo ""

echo "=== Port Status ==="
echo "Checking DashClicks service ports..."
for port in 5000 5001 5002 5003 4000 6001 6002 5008; do
  if lsof -i :$port > /dev/null 2>&1; then
    echo "Port $port: IN USE"
  else
    echo "Port $port: FREE"
  fi
done
echo ""

echo "=== Service Health Checks ==="
for port in 5001 5002 5003; do
  if curl -s http://localhost:$port/status > /dev/null 2>&1; then
    echo "Service on port $port: HEALTHY"
  else
    echo "Service on port $port: NOT RESPONDING"
  fi
done
echo ""

echo "=== Database Connection ==="
if [[ -n "$MONGO_DB_URL" ]]; then
  echo "MongoDB URL configured: YES"
else
  echo "MongoDB URL configured: NO"
fi

echo "=== Shared Files Status ==="
if [[ -d "shared/models" && -d "shared/utilities" ]]; then
  echo "Shared folders exist: YES"
  echo "Models count: $(find shared/models -name "*.js" | wc -l)"
  echo "Utilities count: $(find shared/utilities -name "*.js" | wc -l)"
else
  echo "Shared folders exist: NO"
fi

API Response Testing

Test API responses systematically:

# Test API Router
curl http://localhost:5001/status

# Test Internal API
curl http://localhost:5002/status

# Test External API
curl http://localhost:5003/status

# Test with verbose output for debugging
curl -v http://localhost:5001/status

Getting Further Help

Before Seeking Help

1. Check this troubleshooting guide for your specific issue
2. Review the logs for error messages and context
3. Test with minimal configuration to isolate the problem
4. Verify your environment meets the requirements

Information to Include

When reporting issues, include:

• Error messages (complete stack traces)
• Environment details (OS, Node.js version, package versions)
• Configuration (.env contents without API keys)
• Steps to reproduce the issue
• Expected vs actual behavior

Resources

• Configuration Guide - Environment setup
• Architecture Documentation - System understanding
• API Reference - Endpoint details
• Integration Examples - Working code samples

---

Most issues can be resolved by checking configuration, file permissions, and API key validity. The system is designed to be robust and self-healing, so many problems resolve automatically once the underlying cause is addressed.