Skip to main content

Troubleshooting Guide

This guide helps diagnose and resolve common issues in PulseCRM.

Common Issues​

Authentication Issues​

JWT Token Invalid​

Symptoms:

  • 401 Unauthorized responses
  • Unexpected logouts
  • Token validation errors

Solutions:

  1. Check token expiration
  2. Verify token format
  3. Confirm secret key configuration
  4. Check for clock skew

Session Management​

Symptoms:

  • Multiple re-authentications
  • Lost sessions
  • Concurrent session conflicts

Solutions:

  1. Verify session configuration
  2. Check session storage
  3. Review timeout settings
  4. Monitor session cleanup

Database Issues​

Connection Problems​

Symptoms:

  • Connection timeout errors
  • Pool exhaustion
  • Intermittent failures

Solutions:

  1. Check connection string
  2. Verify database credentials
  3. Monitor connection pool
  4. Review network configuration

Query Performance​

Symptoms:

  • Slow response times
  • Query timeouts
  • High resource usage

Solutions:

  1. Review query plans
  2. Check indexes
  3. Optimize queries
  4. Monitor query cache

API Issues​

Rate Limiting​

Symptoms:

  • 429 Too Many Requests
  • Throttled requests
  • Inconsistent responses

Solutions:

  1. Check rate limit configuration
  2. Implement request queuing
  3. Add retry logic
  4. Monitor usage patterns

Response Errors​

Symptoms:

  • Unexpected 500 errors
  • Inconsistent data
  • Timeout issues

Solutions:

  1. Check error logs
  2. Verify request format
  3. Monitor API health
  4. Review error handling

Diagnostic Tools​

System Health Check​

# Check system status
curl http://localhost:3000/api/health

# Expected response
{
  "status": "healthy",
  "services": {
    "database": "connected",
    "cache": "available",
    "storage": "accessible"
  }
}

Database Diagnostics​

-- Check connection count
SELECT count(*), state 
FROM pg_stat_activity 
GROUP BY state;

-- Identify slow queries
SELECT pid, query, duration 
FROM pg_stat_activity 
WHERE state = 'active' 
ORDER BY duration DESC;

API Diagnostics​

# Test API endpoint with curl
curl -v -H "Authorization: Bearer ${TOKEN}" \
  http://localhost:3000/api/test

# Monitor rate limits
curl -v -H "Authorization: Bearer ${TOKEN}" \
  http://localhost:3000/api/rate-limit-status

Error Messages​

Database Errors​

Connection Failed​

Error: Connection to database failed
Cause: Unable to establish database connection
Solution: 
1. Check database credentials
2. Verify database is running
3. Check network connectivity

Query Failed​

Error: Query execution failed
Cause: Invalid query or database constraint violation
Solution:
1. Check query syntax
2. Verify data constraints
3. Review error details

API Errors​

Authentication Failed​

Error: Authentication failed
Status: 401
Cause: Invalid or expired token
Solution:
1. Check token validity
2. Verify credentials
3. Review authentication flow

Validation Failed​

Error: Validation failed
Status: 400
Cause: Invalid request data
Solution:
1. Check request format
2. Verify required fields
3. Review validation rules

Performance Issues​

Slow Queries​

Symptoms​

  • Long response times
  • High CPU usage
  • Memory pressure

Diagnosis​

  1. Check query plans
  2. Monitor index usage
  3. Review data volume
  4. Analyze query patterns

Solutions​

  1. Optimize indexes
  2. Refactor queries
  3. Implement caching
  4. Consider denormalization

Memory Issues​

Symptoms​

  • High memory usage
  • Garbage collection spikes
  • Out of memory errors

Diagnosis​

  1. Monitor memory usage
  2. Check memory leaks
  3. Review resource allocation
  4. Analyze usage patterns

Solutions​

  1. Optimize memory usage
  2. Implement pooling
  3. Add memory limits
  4. Review resource cleanup

Monitoring​

Key Metrics​

System Health​

  • CPU usage
  • Memory usage
  • Disk space
  • Network traffic

Application Metrics​

  • Response times
  • Error rates
  • Request volume
  • Active users

Database Metrics​

  • Connection count
  • Query performance
  • Lock contention
  • Cache hit ratio

Logging​

Log Levels​

// Log level configuration
const logLevels = {
  error: 0,
  warn: 1,
  info: 2,
  debug: 3
};

// Usage example
logger.error("Critical error", { error });
logger.warn("Warning condition", { details });
logger.info("Operation completed", { result });
logger.debug("Debug information", { data });

Log Analysis​

  1. Review error patterns
  2. Monitor warning trends
  3. Track information flow
  4. Debug specific issues

Recovery Procedures​

Database Recovery​

  1. Check backup status
  2. Stop affected services
  3. Restore from backup
  4. Verify data integrity
  5. Resume services

Service Recovery​

  1. Identify failure point
  2. Stop affected service
  3. Clear corrupt state
  4. Restart service
  5. Verify operation

Data Recovery​

  1. Identify data issue
  2. Stop write operations
  3. Apply corrections
  4. Verify integrity
  5. Resume operations