Troubleshooting Guide

This comprehensive troubleshooting guide covers common issues encountered when developing, deploying, and maintaining AMRnet. The solutions are based on real-world problems and their tested fixes.

Performance Issues

Slow Data Loading (2+ Minute Load Times)

Symptoms: - E. coli data taking 3+ minutes to load - K. pneumoniae taking 2+ minutes - Browser freezing during data fetch - Large payload sizes (75MB+)

Diagnosis Script:

# Test performance issues
node scripts/organism-performance-debugger.js

Root Causes: - Unoptimized MongoDB queries returning all fields - Large datasets (227K+ documents for E. coli) - Single monolithic API calls - Lack of pagination or progressive loading

Solutions:

  1. Use Optimized Endpoints:

// Instead of:
const data = await axios.get('/api/getDataForEcoli'); // 186MB, 21s

// Use:
const data = await axios.get('/api/optimized/map/ecoli'); // 13MB, 7s

  1. Implement Pagination for Large Datasets:

// For E. coli (large dataset)
const firstPage = await axios.get('/api/optimized/paginated/ecoli?page=1&limit=5000');

// Progressive loading
const loadNextPage = async (page) => {
  return axios.get(`/api/optimized/paginated/ecoli?page=${page}&limit=5000`);
};

  1. Use Parallel Loading:

// Load multiple chart sections simultaneously
const [mapData, trendsData, resistanceData] = await Promise.all([
  axios.get('/api/optimized/map/ecoli'),
  axios.get('/api/optimized/trends/ecoli'),
  axios.get('/api/optimized/resistance/ecoli')
]);

Performance Validation:

# Test the fixes
node scripts/real-performance-test.js

Browser Freezing on Large Datasets

Symptoms: - Browser becomes unresponsive - UI freezes during data processing - “Page Unresponsive” warnings

Diagnosis:

# Test for freezing issues
node scripts/ecoli-freeze-debugger.js

Solutions:

  1. Progressive Genotype Loading:

// Prevent freezing with requestIdleCallback
const processGenotypesProgressively = (data) => {
  const batches = chunkArray(data, 1000);
  let processed = [];

  const processBatch = (batchIndex) => {
    if (batchIndex >= batches.length) {
      updateUI(processed);
      return;
    }

    requestIdleCallback(() => {
      processed = [...processed, ...batches[batchIndex]];
      processBatch(batchIndex + 1);
    });
  };

  processBatch(0);
};

  1. Web Workers for Heavy Processing:

// offload heavy data processing
const worker = new Worker('/workers/data-processor.js');

worker.postMessage({ data: largeDataset });
worker.onmessage = (event) => {
  const processedData = event.data;
  updateUI(processedData);
};

Validation:

# Verify fix is working
node scripts/post-fix-validation.js

Development Issues

ESLint Errors and Warnings

Symptoms: - Build failures due to linting errors - Unused variable warnings - Import/export errors

Quick Fix:

# Automated ESLint fixes
./scripts/comprehensive-eslint-fix.sh

Manual Fixes:

# Fix specific issues
cd client
npx eslint src --fix --max-warnings 200

# For development (bypass errors)
ESLINT_NO_DEV_ERRORS=true npm start

Common Issues and Fixes:

// Fix unused theme parameters
// Before:
const useStyles = makeStyles((theme) => ({
  root: { padding: 16 }
}));

// After:
const useStyles = makeStyles((_theme) => ({
  root: { padding: 16 }
}));

// Fix unused parameters in catch blocks
// Before:
.catch((error) => console.log('Error occurred'))

// After:
.catch((_error) => console.log('Error occurred'))

MongoDB Connection Issues

Symptoms: - “Failed to load resource: 500 Internal Server Error” - Connection timeouts - Authentication failures

Diagnosis:

# Test MongoDB connection
node scripts/test-fixie-connection.js

Common Solutions:

  1. Check Environment Variables:

# Verify configuration
echo $MONGODB_URI
echo $NODE_ENV

  1. Fix Connection String Format:

# Correct format
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/dbname?retryWrites=true&w=majority

  1. Test Connection with Retry Logic:

const connectWithRetry = async () => {
  const maxRetries = 3;
  let retries = 0;

  while (retries < maxRetries) {
    try {
      await client.connect();
      return;
    } catch (error) {
      retries++;
      console.log(`Connection attempt ${retries} failed: ${error.message}`);
      if (retries === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
};

Server Startup Issues

Symptoms: - Server not starting on correct port - “EADDRINUSE” port errors - Import/export syntax errors

Solutions:

  1. Port Configuration:

# Start on specific port
PORT=8080 node server.js

  1. Kill Existing Processes:

# Find and kill processes using port
lsof -ti:8080 | xargs kill -9

  1. Use Minimal Test Server:

# Start minimal server for testing
node scripts/test-server.js

Validation:

# Test server endpoints
./scripts/test-api.sh

Deployment Issues

Heroku Deployment Failures

Symptoms: - Build failures during deployment - Memory limit exceeded - Slow response times

Pre-deployment Check:

# Validate deployment readiness
node scripts/deployment-readiness.js

Common Fixes:

  1. Environment Variables:

# Set required variables
heroku config:set NODE_ENV=production
heroku config:set MONGODB_URI="your-connection-string"

  1. Optimize for Heroku:

# Run Heroku-specific optimizations
node scripts/heroku-atlas-optimizer.js

  1. Build Script Issues:

// package.json
{
  "scripts": {
    "heroku-postbuild": "cd client && npm install && npm run build"
  }
}

MongoDB Atlas Performance

Symptoms: - High latency connections - Timeout errors - Poor query performance

Diagnosis:

# Check Atlas performance
node scripts/heroku-atlas-optimizer.js

Optimizations:

1. Region Proximity: - Ensure Heroku and Atlas are in same region - Use us-east-1 for both services

  1. Connection Pooling:

const mongoOptions = {
  maxPoolSize: 10,
  minPoolSize: 5,
  maxIdleTimeMS: 30000,
  serverSelectionTimeoutMS: 5000,
  socketTimeoutMS: 45000
};

Translation and Internationalization

Translation Workflow Issues

Symptoms: - Missing translation keys - Translation workflow not triggering - JSON syntax errors

Validation:

# Test translation setup
./scripts/test-translation-setup.sh

Common Fixes:

  1. File Structure:

# Ensure correct structure
client/
├── locales/
│   ├── en.json
│   ├── fr.json
│   ├── pt.json
│   └── es.json
└── src/
    └── i18n.js

  1. JSON Validation:

# Validate JSON files
python3 -m json.tool client/locales/en.json

  1. GitHub Workflow:

# .github/workflows/translate_app.yml
name: Auto-translate Application
on:
  push:
    paths:
      - 'client/locales/en.json'

Code Quality Issues

Cleanup and Maintenance

Symptoms: - Excessive console.log statements - Commented-out code - Unused files and dependencies

Automated Cleanup:

# Run comprehensive cleanup
./scripts/cleanup.sh

# Code-specific cleanup
./scripts/cleanup_script.sh

Manual Cleanup:

# Remove debugging code
find . -name "*.js" | xargs grep -l "console.log" | head -10

# Find commented code
find . -name "*.js" | xargs grep -l "^[[:space:]]*//.*TODO"

Security Issues

Symptoms: - Exposed credentials in repository - Security warnings - Vulnerable dependencies

Immediate Actions:

# Check for exposed secrets
git log --all --full-history -- .env*

# Security audit
npm audit

# Fix vulnerabilities
npm audit fix

Prevention:

# .gitignore
.env
.env.*
!.env.example

Performance Optimization

Monitoring and Validation

Real-time Monitoring:

# Monitor performance
node scripts/monitor-performance.js

Load Testing:

# Test endpoint performance
node scripts/test-optimized-endpoints.js

Performance Benchmarks:

# Comprehensive performance test
node scripts/test-performance.js

Expected Results: - K. pneumoniae: <2s load time - E. coli: <7s with pagination - E. coli (diarrheagenic): <3s load time - Payload reduction: 60-90%

Diagnostic Scripts Reference

Quick Diagnostics:

# Health check
curl http://localhost:8080/api/health

# Performance check
node scripts/real-performance-test.js

# Deployment readiness
node scripts/deployment-readiness.js

Comprehensive Analysis:

# Full performance analysis
node scripts/organism-performance-debugger.js

# Heroku/Atlas optimization
node scripts/heroku-atlas-optimizer.js

# Translation validation
./scripts/test-translation-setup.sh

Status Checks:

# Project status
./scripts/status-check.sh

# API endpoints test
./scripts/test-api.sh

Emergency Procedures

Critical Performance Issues

If users report 2+ minute load times:

  1. Immediate Response:

# Switch to optimized endpoints
# Update frontend API calls from /api/ to /api/optimized/

  1. Verify Fix:

node scripts/post-fix-validation.js

  1. Monitor Results:

node scripts/monitor-performance.js

Server Down Emergency

If server is unresponsive:

  1. Start Minimal Server:

node scripts/minimal-server.js

  1. Check Logs:

heroku logs --tail

  1. Restart with Fixed Configuration:

node scripts/server-fixed.js

Getting Help

When to Use Each Script:

  • Performance Issues: organism-performance-debugger.js

  • Deployment Problems: deployment-readiness.js

  • MongoDB Issues: test-fixie-connection.js

  • Code Quality: cleanup_script.sh

  • Translation Issues: test-translation-setup.sh

Community Support: - GitHub Issues: https://github.com/amrnet/amrnet/issues - Discussions: https://github.com/amrnet/amrnet/discussions - Email: amrnetdashboard@gmail.com

Emergency Contacts: - Critical bugs: GitHub Issues with “urgent” label - Security issues: amrnetdashboard@gmail.com