Common Issues

This guide covers common issues encountered when deploying and operating License Monitor and License Server Detail.

License Monitor Issues

Service Won’t Start

Symptoms: License Monitor fails to start or exits immediately.

1. Check configuration syntax

   /usr/local/bin/license_monitor --config /etc/license-monitor/config.toml --debug

2. Verify file permissions

   ls -la /etc/license-monitor/
   ls -la /var/log/license-monitor/

3. Check port availability

   ss -tlnp | grep 8080
   # If port in use, change bind_port in config

4. Review system logs

   journalctl -u license-monitor -n 50

Common causes:

• Invalid TOML syntax in config file
• Port already in use
• Insufficient permissions on log directory
• Missing required dependencies

API Not Responding

Symptoms: Requests to API endpoints timeout or return errors.

Check	Command	Expected
Service running	systemctl status license-monitor	Active
Port listening	ss -tlnp | grep 8080	LISTEN
Firewall	iptables -L -n | grep 8080	ACCEPT
Process health	curl localhost:8080/api/health	200 OK

Resolution:

# Restart service
systemctl restart license-monitor

# Check if binding to correct interface
grep bind_address /etc/license-monitor/config.toml
# Should be 0.0.0.0 if accessed remotely (with firewall protection)

License Query Fails

Symptoms: /api/licenses returns errors or empty data.

1. Test command manually

   # Run the same command License Monitor uses
   lmstat -a -c 27000@license-server

2. Check license server connectivity

   telnet license-server 27000

3. Verify parse script

   # Test parse script with sample output
   echo "sample output" | python3 /etc/license-monitor/servers/parse.py

4. Check error logs

   grep "LICENSE_QUERY" /var/log/license-monitor/license_monitor.log

WebSocket Connection Drops

Symptoms: WebSocket connections disconnect unexpectedly.

Common causes and solutions:

Cause	Solution
Proxy timeout	Increase proxy timeout to 86400s
Idle timeout	Implement ping/pong keep-alive
Rate limiting	Increase rate limits
Memory pressure	Increase memory limits

# nginx WebSocket proxy fix
location /ws/ {
    proxy_pass http://license_monitor;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;  # 24 hours
}

License Server Detail Issues

Authentication Failures

Symptoms: Cannot sign in, redirect loops, or session issues.

1. Verify Okta configuration

   # Check environment variables
   echo $AUTH_OKTA_ID
   echo $AUTH_OKTA_ISSUER
   # Never echo AUTH_OKTA_SECRET

2. Check redirect URIs in Okta

   • Sign-in: https://your-domain/api/auth/callback/okta
   • Sign-out: https://your-domain

3. Verify NEXTAUTH_URL

   echo $NEXTAUTH_URL
   # Must match your public domain

4. Check browser console for errors

   • Look for CORS errors
   • Check for blocked cookies

Common Okta errors:

Error	Cause	Solution
invalid_client	Wrong client ID/secret	Verify credentials
redirect_uri_mismatch	URI not configured	Add URI in Okta
access_denied	User not assigned	Assign user to app

Dashboard Not Loading

Symptoms: Blank page, JavaScript errors, or loading spinner.

1. Check browser console

   • Press F12 → Console tab
   • Look for JavaScript errors

2. Verify API connectivity

   curl http://localhost:3000/api/health

3. Check Convex connection

   • Verify CONVEX_URL environment variable
   • Check Convex dashboard for errors

4. Clear browser cache

   • Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)

Real-Time Updates Not Working

Symptoms: Dashboard doesn’t update, stale data displayed.

Component	Check	Solution
WebSocket	Browser DevTools → Network → WS	Reconnect
SSE	Network tab → EventStream	Clear cache
Convex	Convex dashboard → Logs	Check subscription
API	/api/health response	Restart service

// Check WebSocket connection in browser console
const ws = new WebSocket('ws://localhost:8080/ws/logs?api_key=KEY');
ws.onopen = () => console.log('Connected');
ws.onerror = (e) => console.log('Error', e);

Connection Issues

Cannot Connect to License Monitor

Symptoms: Dashboard shows “Connection failed” errors.

1. Verify License Monitor is running

   curl http://license-monitor-host:8080/api/health

2. Check network connectivity

   ping license-monitor-host
   telnet license-monitor-host 8080

3. Verify firewall rules

   # On License Monitor host
   iptables -L -n | grep 8080

4. Check CORS configuration

   # License Monitor config.toml
   [api]
   cors_enabled = true
   cors_origins = ["https://dashboard.example.com"]

SSL/TLS Errors

Symptoms: Certificate errors, HTTPS connection failures.

Error	Cause	Solution
CERT_NOT_TRUSTED	Self-signed cert	Add to trust store
CERT_EXPIRED	Expired certificate	Renew certificate
HOSTNAME_MISMATCH	Wrong domain	Use correct domain
PROTOCOL_ERROR	TLS version mismatch	Update TLS config

# Test SSL certificate
openssl s_client -connect api.example.com:443 -servername api.example.com

# Check certificate expiry
echo | openssl s_client -connect api.example.com:443 2>/dev/null | \
    openssl x509 -noout -dates

Performance Issues

High CPU Usage

Symptoms: Service using excessive CPU.

Possible causes:

• Too frequent polling interval
• Complex regex patterns
• High log volume

Solutions:

# Increase polling interval
[command_mode]
interval_seconds = 600  # 10 minutes instead of 5

# Simplify regex if using tail mode
[tail_mode]
regex_pattern = "^\\d{4}"  # Simpler pattern

High Memory Usage

Symptoms: Memory consumption grows over time.

# Check memory usage
ps aux | grep license_monitor

# If memory is high, check for:
# - Large log buffers
# - Too many WebSocket connections
# - Memory leaks (report as bug)

Solutions:

• Reduce log buffer size
• Limit concurrent connections
• Restart service periodically

Tip

For persistent issues, enable debug logging temporarily to gather more information:

export LICENSE_MONITOR_LOG_LEVEL=debug
systemctl restart license-monitor
# After reproducing issue
export LICENSE_MONITOR_LOG_LEVEL=warn

Next Steps

• Debugging Guide - Step-by-step debugging
• Log Analysis - Understanding logs
• Performance - Performance tuning