Countly Troubleshooting and Debugging | Blue Frog Docs

Countly Troubleshooting and Debugging

Diagnose and resolve common issues with Countly analytics implementation and data collection.

Troubleshooting Overview

This guide covers common issues with Countly analytics and provides solutions for installation, data collection, and server problems.

 

 

SDK Installation Issues

SDK Not Initializing

Symptoms:

Web SDK Debugging:

// Enable debug mode
Countly.debug = true;

Countly.init({
  app_key: 'YOUR_APP_KEY',
  url: 'https://your-server.com',
  debug: true
});

// Check console for detailed logs

Mobile SDK Debugging:

// iOS
config.enableDebug = true
config.logLevel = .debug

// Android
config.setLoggingEnabled(true)
Countly.sharedInstance().setLoggingEnabled(true)

Wrong Server URL

Common Mistakes:

  • Missing protocol (https://)
  • Trailing slash issues
  • Wrong port number

Correct Format:

// Correct
url: 'https://your-countly-server.com'

// Incorrect
url: 'your-countly-server.com'           // Missing protocol
url: 'https://your-countly-server.com/'  // Trailing slash may cause issues

App Key Mismatch

  1. Go to Countly dashboard → Management → Applications
  2. Copy the correct App Key
  3. Update SDK configuration
  4. Verify the key matches exactly (case-sensitive)

 

 

Data Collection Problems

Events Not Recording

Diagnostic Steps:

  1. Enable SDK debug mode
  2. Check console/logs for event sending
  3. Verify event structure is valid

Common Issues:

// Missing required 'key' property
Countly.add_event({
  count: 1  // ❌ Missing 'key'
});

// Correct
Countly.add_event({
  key: 'event_name',  // ✓ Required
  count: 1
});

Sessions Not Tracking

Web SDK:

// Ensure session tracking is enabled
Countly.track_sessions();

// For SPAs, track page changes
Countly.track_pageview();

Mobile SDK:

// iOS - Sessions are automatic with proper lifecycle
config.features = [.sessions]

Missing User Data

Check User Identification:

// Verify device_id is set
console.log(Countly.get_device_id());

// For logged-in users
Countly.change_id('new_user_id');

 

 

Server Issues (Self-Hosted)

Server Not Responding

Check Server Status:

# Check if Countly is running
sudo countly status

# Check logs
tail -f /var/log/countly/countly.log

# Check API server
curl -I https://your-server.com/o/ping

MongoDB Connection Issues

# Check MongoDB status
sudo systemctl status mongod

# Check MongoDB connection
mongo --eval "db.adminCommand('ismaster')"

# Review MongoDB logs
tail -f /var/log/mongodb/mongod.log

Nginx/Proxy Issues

# Test Nginx configuration
sudo nginx -t

# Check Nginx logs
tail -f /var/log/nginx/error.log

# Restart Nginx
sudo systemctl restart nginx

High CPU/Memory Usage

# Check resource usage
htop

# Identify heavy processes
ps aux | grep countly

# Check MongoDB memory
mongo --eval "db.serverStatus().mem"

Common Causes:

  • Too many concurrent requests
  • Large aggregation queries
  • Insufficient RAM for dataset size
  • Unoptimized MongoDB indexes

 

 

Push Notification Issues

Push Not Delivered

FCM (Android) Debugging:

  1. Verify FCM credentials in Countly settings
  2. Check device token is registered:
Countly.sharedInstance().push().getToken(object : TokenCallback {
    override fun onToken(token: String?) {
        Log.d("Countly", "Token: $token")
    }
})
  1. Test with FCM console directly

APNs (iOS) Debugging:

  1. Verify certificate type (development vs production)
  2. Check provisioning profile includes push
  3. Verify device token registration:
print("Push token: \(deviceToken.map { String(format: "%02.2hhx", $0) }.joined())")

Push Token Not Registering

// Web Push - Check permission status
Notification.requestPermission().then(permission => {
  console.log('Push permission:', permission);
});

// Verify service worker
navigator.serviceWorker.ready.then(registration => {
  console.log('Service worker ready:', registration);
});

 

 

Crash Reporting Issues

Crashes Not Appearing

Check SDK Configuration:

// Web
Countly.init({
  app_key: 'YOUR_APP_KEY',
  url: 'https://your-server.com',
  features: ['crashes']
});
Countly.track_errors();

// iOS
config.features = [.crashReporting]

// Android
config.enableCrashReporting()

Test Crash Reporting:

// Force a test crash
Countly.add_log("Testing crash");
throw new Error("Test crash for Countly");

Symbolication Not Working

iOS:

  1. Upload dSYM files to Countly
  2. Verify build UUID matches
  3. Check symbolication plugin is installed

Android:

  1. Upload mapping files (ProGuard/R8)
  2. Configure automatic upload in build.gradle
  3. Verify version codes match

 

 

Dashboard Issues

Data Not Displaying

Check Date Range:

  • Ensure selected date range includes data
  • Check timezone settings match data collection

Verify Permissions:

  • Confirm user has access to the app
  • Check feature permissions are enabled

Slow Dashboard Performance

For Self-Hosted:

# Rebuild indexes
mongo countly --eval "db.events.reIndex()"

# Check disk usage
df -h

# Clear old data if needed
countly api cleanup

Common Fixes:

  • Increase server RAM
  • Enable data aggregation
  • Archive old data
  • Optimize MongoDB configuration

 

 

Network and Connectivity

CORS Errors

For Self-Hosted Servers:

# nginx configuration
location / {
    add_header 'Access-Control-Allow-Origin' '*';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'Content-Type';
}

SSL/TLS Issues

# Test SSL certificate
openssl s_client -connect your-server.com:443

# Check certificate expiration
echo | openssl s_client -servername your-server.com -connect your-server.com:443 2>/dev/null | openssl x509 -noout -dates

Request Queuing (Offline Mode)

// Check queue status
console.log(Countly.get_queue_size());

// Force queue processing
Countly.process_queue();

 

 

Getting Help

Community Support

  • GitHub Issues: github.com/Countly/countly-server
  • Community Forum: community.countly.com
  • Documentation: support.countly.com

Enterprise Support

Enterprise customers have access to:

  • Priority support tickets
  • Direct engineering support
  • Custom troubleshooting assistance

Information to Provide

When seeking help, include:

  • Countly version (server and SDK)
  • Platform and device information
  • Steps to reproduce
  • Relevant log output
  • Configuration snippets (redact sensitive data)
↑ Back to top
// SYS.FOOTER