Documentation
Technical Documentation/Troubleshooting Guide

Troubleshooting Guide

The ReadyGolf platform includes comprehensive troubleshooting tools and resources to help resolve common issues quickly. This guide covers diagnostic procedures, error resolution, and support escalation processes.

🎯 Troubleshooting Overview

ReadyGolf provides multiple layers of troubleshooting support, from self-service diagnostic tools to expert technical support. This guide helps you identify, diagnose, and resolve common issues efficiently.

Support Tiers

  • Self-Service: Documentation, diagnostic tools, and community resources
  • Technical Support: Expert assistance for complex issues
  • Emergency Support: Critical system failures and outages

🔍 Diagnostic Tools

Health Check Endpoints

Application Health

# Check application status
curl https://readygolf.com/api/health

# Expected response:
{
  "status": "healthy",
  "timestamp": "2024-01-20T15:30:00Z",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "stripe": "healthy"
  }
}

Database Health

# Check database connectivity
curl https://readygolf.com/api/health/database

# Check database performance
curl https://readygolf.com/api/health/database/performance

External Services

# Check payment processor status
curl https://readygolf.com/api/health/payments

# Check email service status
curl https://readygolf.com/api/health/email

# Check file storage status
curl https://readygolf.com/api/health/storage

Log Analysis Tools

Application Logs

# View application logs
tail -f /var/log/readygolf/app.log

# Search for errors
grep -i error /var/log/readygolf/app.log

# Search for specific user activity
grep "user_id:123" /var/log/readygolf/app.log

# Monitor real-time logs
tail -f /var/log/readygolf/app.log | grep -E "(ERROR|WARN|FATAL)"

Database Logs

# PostgreSQL logs
tail -f /var/log/postgresql/postgresql-14-main.log

# Slow query analysis
sudo -u postgres psql -c "
SELECT query, mean_time, calls, total_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;
"

System Logs

# System resource usage
htop
iostat -x 1
df -h

# Network connectivity
netstat -tulpn | grep :3000
ss -tulpn | grep :3000

🚨 Common Issues & Solutions

Authentication Issues

Problem: "Authentication required" error

Symptoms:

  • Users cannot log in
  • API requests return 401 errors
  • Session tokens not working

Diagnosis:

# Check JWT configuration
echo $JWT_SECRET
echo $JWT_EXPIRES_IN

# Verify session storage
redis-cli keys "session:*"

Solutions:

  1. Check JWT Secret: Ensure JWT_SECRET environment variable is set
  2. Verify Token Expiry: Check JWT_EXPIRES_IN configuration
  3. Clear Session Cache: Restart Redis or clear session data
  4. Check Database: Verify user accounts exist and are active
// Debug authentication middleware
app.use('/api/*', (req, res, next) => {
  console.log('Auth headers:', req.headers.authorization);
  console.log('Session:', req.session);
  next();
});

Problem: Multi-factor authentication not working

Symptoms:

  • MFA codes not being sent
  • Users cannot complete MFA setup
  • MFA bypass not working

Diagnosis:

# Check SMS provider configuration
echo $TWILIO_ACCOUNT_SID
echo $TWILIO_AUTH_TOKEN

# Check email configuration
echo $SMTP_HOST
echo $SMTP_USER

Solutions:

  1. Verify SMS Provider: Check Twilio credentials and account status
  2. Test Email Service: Verify SMTP configuration
  3. Check MFA Settings: Review MFA configuration in admin panel
  4. Reset MFA: Allow users to reset MFA if needed

Database Issues

Problem: Database connection errors

Symptoms:

  • "Database connection failed" errors
  • Slow response times
  • Application crashes

Diagnosis:

# Test database connectivity
psql $DATABASE_URL -c "SELECT 1;"

# Check connection pool
psql $DATABASE_URL -c "
SELECT count(*) as active_connections 
FROM pg_stat_activity 
WHERE state = 'active';
"

# Check database locks
psql $DATABASE_URL -c "
SELECT pid, usename, application_name, state, query
FROM pg_stat_activity
WHERE state = 'active';
"

Solutions:

  1. Increase Connection Pool: Adjust DATABASE_POOL_SIZE
  2. Optimise Queries: Review slow queries and add indexes
  3. Restart Database: Restart PostgreSQL service
  4. Check Resource Limits: Monitor CPU, memory, and disk usage
-- Add missing indexes
CREATE INDEX CONCURRENTLY idx_bookings_date_org ON bookings(date, organization_id);
CREATE INDEX CONCURRENTLY idx_members_email ON members(email);
CREATE INDEX CONCURRENTLY idx_transactions_created ON transactions(created_at);

-- Analyse table statistics
ANALYZE bookings;
ANALYZE members;
ANALYZE transactions;

Problem: Database migration failures

Symptoms:

  • Migration errors during deployment
  • Schema inconsistencies
  • Data integrity issues

Diagnosis:

# Check migration status
npm run db:migrate:status

# View migration history
psql $DATABASE_URL -c "
SELECT * FROM _prisma_migrations 
ORDER BY finished_at DESC;
"

Solutions:

  1. Rollback Migration: Use npm run db:migrate:rollback
  2. Fix Migration Script: Correct migration file and re-run
  3. Manual Schema Update: Apply changes manually if needed
  4. Restore from Backup: Use backup if data corruption occurs

Payment Processing Issues

Problem: Stripe payment failures

Symptoms:

  • Payment declined errors
  • Webhook delivery failures
  • Inconsistent payment status

Diagnosis:

# Check Stripe configuration
echo $STRIPE_PUBLISHABLE_KEY
echo $STRIPE_SECRET_KEY
echo $STRIPE_WEBHOOK_SECRET

# Test Stripe connectivity
curl -u $STRIPE_SECRET_KEY: https://api.stripe.com/v1/charges

Solutions:

  1. Verify API Keys: Ensure correct Stripe keys are configured
  2. Check Webhook Endpoints: Verify webhook URL and secret
  3. Review Payment Methods: Ensure supported payment methods are enabled
  4. Check Account Status: Verify Stripe account is active and not restricted
// Debug payment processing
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

// Test payment intent creation
const paymentIntent = await stripe.paymentIntents.create({
  amount: 1000,
  currency: 'gbp',
  metadata: { test: 'true' }
});

console.log('Payment Intent:', paymentIntent);

Problem: PayPal integration issues

Symptoms:

  • PayPal payments not processing
  • Order creation failures
  • Payment capture errors

Diagnosis:

# Check PayPal configuration
echo $PAYPAL_CLIENT_ID
echo $PAYPAL_CLIENT_SECRET
echo $PAYPAL_ENVIRONMENT

Solutions:

  1. Verify Credentials: Check PayPal API credentials
  2. Test Environment: Ensure correct environment (sandbox/live)
  3. Check Webhooks: Verify PayPal webhook configuration
  4. Review Permissions: Ensure PayPal account has required permissions

Email Delivery Issues

Problem: Email not being sent

Symptoms:

  • Users not receiving confirmation emails
  • Password reset emails not delivered
  • Newsletter delivery failures

Diagnosis:

# Test SMTP configuration
telnet $SMTP_HOST $SMTP_PORT

# Check email logs
tail -f /var/log/mail.log

# Test email sending
node -e "
const nodemailer = require('nodemailer');
const transporter = nodemailer.createTransporter({
  host: process.env.SMTP_HOST,
  port: process.env.SMTP_PORT,
  secure: false,
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASSWORD
  }
});

transporter.sendMail({
  from: process.env.EMAIL_FROM,
  to: 'test@example.com',
  subject: 'Test Email',
  text: 'This is a test email'
}).then(console.log).catch(console.error);
"

Solutions:

  1. Check SMTP Settings: Verify host, port, and credentials
  2. Review Email Limits: Check sending limits and quotas
  3. Monitor Spam Filters: Ensure emails aren't being marked as spam
  4. Test Email Templates: Verify email template syntax

Performance Issues

Problem: Slow application response

Symptoms:

  • Long page load times
  • API timeouts
  • High server resource usage

Diagnosis:

# Check server resources
top
htop
iostat -x 1

# Monitor application performance
curl -w "@curl-format.txt" -o /dev/null -s "https://readygolf.com/api/health"

# Check database performance
psql $DATABASE_URL -c "
SELECT query, mean_time, calls, total_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;
"

Solutions:

  1. Optimise Database Queries: Add indexes and optimise slow queries
  2. Implement Caching: Use Redis for session and data caching
  3. Scale Resources: Increase CPU, memory, or database resources
  4. CDN Configuration: Use CDN for static assets
// Performance monitoring
const startTime = Date.now();

// Your operation here
const result = await databaseOperation();

const duration = Date.now() - startTime;
console.log(`Operation took ${duration}ms`);

if (duration > 1000) {
  console.warn('Slow operation detected');
}

Problem: Memory leaks

Symptoms:

  • Increasing memory usage over time
  • Application crashes
  • Slow performance

Diagnosis:

# Monitor memory usage
watch -n 1 'free -h'

# Check for memory leaks
node --inspect app.js

# Analyse heap dumps
node --heapsnapshot app.js

Solutions:

  1. Review Code: Check for unclosed connections and event listeners
  2. Implement Garbage Collection: Force garbage collection if needed
  3. Monitor Memory Usage: Set up alerts for high memory usage
  4. Restart Application: Schedule regular restarts if needed

🔧 Debugging Techniques

Application Debugging

Enable Debug Logging

// Enable debug mode
process.env.DEBUG = 'readygolf:*';
process.env.LOG_LEVEL = 'debug';

// Custom debug logging
const debug = require('debug')('readygolf:api');

debug('Processing request:', { url: req.url, method: req.method });

Error Tracking

// Enhanced error logging
app.use((error, req, res, next) => {
  console.error('Error details:', {
    message: error.message,
    stack: error.stack,
    url: req.url,
    method: req.method,
    userAgent: req.get('User-Agent'),
    ip: req.ip,
    timestamp: new Date().toISOString()
  });
  
  // Send to error tracking service
  Sentry.captureException(error, {
    extra: {
      url: req.url,
      method: req.method,
      userId: req.user?.id
    }
  });
  
  next(error);
});

API Debugging

# Test API endpoints
curl -X GET https://readygolf.com/api/health \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -v

# Debug webhook delivery
curl -X POST https://readygolf.com/api/webhooks/stripe \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: YOUR_SIGNATURE" \
  -d '{"test": "data"}' \
  -v

Database Debugging

Query Analysis

-- Enable query logging
SET log_statement = 'all';
SET log_min_duration_statement = 1000;

-- Analyse slow queries
SELECT query, mean_time, calls, total_time
FROM pg_stat_statements
WHERE mean_time > 1000
ORDER BY mean_time DESC;

-- Check table sizes
SELECT 
  schemaname,
  tablename,
  attname,
  n_distinct,
  correlation
FROM pg_stats
WHERE tablename = 'bookings';

Performance Monitoring

-- Monitor active connections
SELECT 
  pid,
  usename,
  application_name,
  client_addr,
  state,
  query_start,
  query
FROM pg_stat_activity
WHERE state = 'active';

-- Check table bloat
SELECT 
  schemaname,
  tablename,
  attname,
  n_distinct,
  correlation
FROM pg_stats
WHERE schemaname = 'public';

📞 Support Escalation

Support Levels

Level 1: Self-Service

  • Resources: Documentation, FAQ, community forums
  • Response Time: Immediate
  • Resolution: Self-guided troubleshooting

Level 2: Technical Support

  • Contact: support@readygolf.com
  • Response Time: 4-8 hours
  • Resolution: Expert assistance for complex issues

Level 3: Emergency Support

Support Request Template

## Issue Report

**Priority**: [Low/Medium/High/Critical]
**Environment**: [Development/Staging/Production]
**Affected Users**: [Number or description]

### Problem Description
[Detailed description of the issue]

### Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Expected Behaviour
[What should happen]

### Actual Behaviour
[What is actually happening]

### Error Messages
[Copy any error messages or logs]

### System Information
- **Platform**: [Operating system]
- **Browser**: [If applicable]
- **Version**: [Application version]
- **Database**: [Database version]

### Attempted Solutions
[What you've already tried]

### Additional Context
[Any other relevant information]

Emergency Procedures

Critical System Failure

  1. Immediate Actions:

    • Check system health endpoints
    • Review error logs
    • Contact emergency support
    • Notify stakeholders

  2. Recovery Steps:

    • Restart affected services
    • Restore from backup if needed
    • Verify system functionality
    • Document incident

  3. Post-Incident:

    • Conduct root cause analysis
    • Implement preventive measures
    • Update documentation
    • Review procedures

Data Loss or Corruption

  1. Assessment:

    • Identify affected data
    • Determine scope of loss
    • Check backup availability

  2. Recovery:

    • Restore from latest backup
    • Verify data integrity
    • Test system functionality

  3. Prevention:

    • Review backup procedures
    • Implement additional safeguards
    • Update disaster recovery plan

📚 Additional Resources

Documentation

  • API Documentation: Complete API reference and examples
  • Integration Guides: Third-party service integration
  • Configuration Guide: System configuration and setup
  • Deployment Guide: Production deployment procedures

Community Support

  • GitHub Issues: Bug reports and feature requests
  • Community Forum: User discussions and solutions
  • Stack Overflow: Tagged questions and answers
  • Discord Server: Real-time community support

Monitoring Tools

  • Application Monitoring: Sentry, New Relic, DataDog
  • Database Monitoring: pgAdmin, pg_stat_statements
  • Server Monitoring: Prometheus, Grafana, Nagios
  • Uptime Monitoring: Pingdom, UptimeRobot, StatusCake

Training Resources

  • Video Tutorials: Step-by-step guides
  • Webinars: Live training sessions
  • Documentation: Comprehensive guides
  • Best Practices: Recommended procedures

Still need help? Contact our support team at support@readygolf.com or check our community forum for additional assistance.

Deployment Guide

Previous Page