Skip to main content

Troubleshooting Guide

This guide helps you resolve common issues with ThingConnect Pulse. Follow the diagnostic steps to identify and fix problems quickly.

Service Issues​

Service Won't Start​

Symptoms:

  • Cannot access web interface at localhost:8090
  • Service shows "Stopped" in Services console
  • System errors during startup

Diagnostic Steps:

  1. Check service status:

    sc query ThingConnectPulseSvc

  2. Review service logs:

    C:\ProgramData\ThingConnect.Pulse\logs\pulse-[date].log

  3. Check Windows Event Log:

    • Open Event Viewer
    • Navigate to Windows Logs → Application
    • Look for ThingConnect Pulse entries

Common Solutions:

Port 8090 Already in Use

  • Stop other services using port 8090
  • Check with: netstat -an | findstr :8090
  • Restart ThingConnect Pulse service

.NET Runtime Missing

  • Install .NET 8.0 Runtime
  • Download from Microsoft's official site
  • Restart service after installation

Permission Issues

  • Ensure service runs with proper permissions
  • Try running as Local System account temporarily
  • Check file/folder permissions in C:\ProgramData\ThingConnect.Pulse

Service Crashes Frequently​

Diagnostic Steps:

  1. Check crash logs:

    C:\ProgramData\ThingConnect.Pulse\logs\

  2. Monitor resource usage:

    • Task Manager → Performance
    • Look for memory leaks or high CPU usage

  3. Review configuration:

    • Validate YAML syntax
    • Check for excessive endpoint counts
    • Verify probe intervals aren't too aggressive

Common Solutions:

Memory Issues

  • Reduce number of monitored endpoints
  • Increase probe intervals
  • Check for memory leaks in logs

Configuration Errors

  • Validate YAML configuration
  • Remove problematic endpoints temporarily
  • Check network connectivity to targets

Database Corruption

  • Stop service
  • Backup and delete database file
  • Restart service (database will be recreated)
Database Reset

Deleting the database file will remove all historical data. Only do this as a last resort and ensure you have backups if historical data is important.

Web Interface Issues​

Cannot Access Dashboard​

Symptoms:

  • Browser shows "This site can't be reached"
  • Connection timeout errors
  • Blank page or loading errors

Diagnostic Steps:

  1. Verify service is running:

    sc query ThingConnectPulseSvc

  2. Check correct URL:

    • Default: http://localhost:8090
    • Try: http://127.0.0.1:8090
    • Avoid: https:// (use HTTP, not HTTPS)

  3. Test network connectivity:

    telnet localhost 8090

Common Solutions:

Service Not Running

  • Start the service: net start ThingConnectPulseSvc
  • Check logs for startup errors

Firewall Blocking Connection

  • Add exception for port 8090
  • Temporarily disable Windows Firewall to test
  • Check corporate firewall rules

Browser Issues

  • Try different browser or incognito mode
  • Clear browser cache and cookies
  • Disable browser extensions

Login Issues​

Symptoms:

  • Cannot create initial admin account
  • Login fails with correct credentials
  • Infinite login redirects

Diagnostic Steps:

  1. Check browser console for errors
  2. Verify database connectivity
  3. Review authentication logs

Common Solutions:

Initial Setup Problems

  • Clear browser data completely
  • Use incognito/private browsing mode
  • Try different browser

Authentication Database Issues

  • Check database file permissions
  • Restart service to reset session state
  • Delete user data and recreate account

Session Cookie Problems

  • Clear all cookies for localhost
  • Check system clock accuracy
  • Verify browser accepts cookies

User Management Issues​

Symptoms:

  • Cannot create new users
  • User roles not working correctly
  • Account lockout problems

Diagnostic Steps:

  1. Check administrator privileges:

    • Verify current user has Administrator role
    • Review user management permissions

  2. Database user table:

    • Check AspNetUsers table in database
    • Verify user roles are correctly stored

Common Solutions:

Permission Denied Errors

  • Only Administrator role users can manage other users
  • User role users cannot access user management features
  • Check role assignment in database

User Creation Failures

  • Username must be unique across all users
  • Email address must be unique and valid format
  • Password must meet complexity requirements (8+ chars, mixed case, numbers, symbols)
  • Confirm password must match exactly

Account Lockout Issues

  • 5 failed login attempts trigger 30-minute lockout
  • Only administrators can reset lockout status
  • Check user account status in user management interface

Role Assignment Problems

  • Cannot demote the last active administrator
  • Role changes take effect immediately
  • Users must re-login to get updated permissions

Network and Connectivity Issues​

Endpoints Show as DOWN When They're UP​

Symptoms:

  • Known-good devices show DOWN status
  • Inconsistent monitoring results
  • Timeout errors in logs

Diagnostic Steps:

  1. Test connectivity manually:

    ping [target-ip]
    telnet [target-ip] [port]

  2. Check probe configuration:

    • Verify timeouts aren't too short
    • Check if endpoints are actually reachable
    • Review interval settings

  3. Network path analysis:

    • Trace route to target
    • Check for network congestion
    • Verify firewall rules

Common Solutions:

Timeout Too Short

  • Increase timeout values in configuration
  • Consider network latency to targets
  • Use longer intervals for distant devices

Network Path Issues

  • Configure firewalls to allow monitoring traffic
  • Check routing between Pulse server and targets
  • Verify DNS resolution for hostname targets

Probe Configuration Errors

  • Verify correct ports for TCP probes
  • Check HTTP paths and expected content
  • Ensure ICMP is allowed through firewalls

Slow Response Times​

Symptoms:

  • High response times in dashboard
  • Gradual performance degradation
  • Timeouts during peak hours

Diagnostic Steps:

  1. Baseline testing:

    ping -t [target-ip]

  2. Network utilization check:

    • Monitor bandwidth usage
    • Check for network congestion
    • Verify Quality of Service (QoS) settings

  3. Target device performance:

    • Check CPU/memory usage on targets
    • Verify service health on target devices
    • Monitor concurrent connection limits

Common Solutions:

Network Congestion

  • Implement QoS for monitoring traffic
  • Reduce probe frequencies during peak hours
  • Use local network monitoring where possible

Target Overload

  • Reduce probe frequency
  • Distribute monitoring across multiple servers
  • Check target device performance

DNS Resolution Delays

  • Use IP addresses instead of hostnames
  • Configure local DNS servers
  • Check DNS server performance

Configuration Issues​

YAML Validation Errors​

Symptoms:

  • Configuration apply fails
  • "Invalid YAML syntax" errors
  • Parsing errors in interface

Diagnostic Steps:

  1. Check YAML syntax:

    • Use online YAML validator
    • Verify indentation (2 spaces, not tabs)
    • Check for special characters

  2. Review error messages:

    • Read validation errors carefully
    • Check line numbers in error messages
    • Verify required fields are present

Common Solutions:

Indentation Errors

  • Use 2 spaces for indentation
  • Never use tabs
  • Ensure consistent spacing throughout

Missing Required Fields

  • Every target needs: type, group, and host/cidr/wildcard
  • TCP targets require port numbers
  • All groups need id and name

Invalid Values

  • Check group IDs match between groups and targets
  • Verify port numbers are valid (1-65535)
  • Ensure interval and timeout values are reasonable

Configuration Not Taking Effect​

Symptoms:

  • YAML applies successfully but monitoring unchanged
  • Old endpoints still appear
  • New endpoints not discovered

Diagnostic Steps:

  1. Check configuration version:

    • Verify new version was created
    • Check configuration history

  2. Review discovery process:

    • Check logs for discovery errors
    • Verify CIDR ranges and wildcards
    • Monitor endpoint creation in real-time

Common Solutions:

Discovery Issues

  • Verify CIDR notation is correct
  • Check that wildcard ranges are reachable
  • Allow time for endpoint discovery process

Background Processing Delays

  • Wait 2-3 minutes for changes to take effect
  • Check background service logs
  • Restart service if changes don't appear

Configuration Caching

  • Refresh browser page
  • Clear browser cache
  • Check for multiple browser tabs with old data
Configuration Changes

Configuration changes may take 2-3 minutes to fully take effect due to background processing. Be patient and check logs if changes don't appear immediately.

Performance Issues​

High CPU Usage​

Symptoms:

  • Pulse service using excessive CPU
  • System becomes unresponsive
  • Slow dashboard loading

Diagnostic Steps:

  1. Monitor resource usage:

    tasklist /FI "IMAGENAME eq ThingConnect.Pulse.Server.exe"

  2. Check monitoring configuration:

    • Count total endpoints
    • Review probe intervals
    • Calculate total probe rate

Common Solutions:

Too Many Endpoints

  • Reduce number of monitored targets
  • Increase probe intervals
  • Remove unnecessary endpoints

Aggressive Probe Intervals

  • Use 60+ second intervals for non-critical devices
  • Stagger probe timing across endpoints
  • Consider using CIDR ranges instead of individual IPs

Database Performance

  • Check database file size
  • Consider moving database to faster storage
  • Monitor disk I/O usage

Slow Dashboard Loading​

Symptoms:

  • Web interface takes long to load
  • Timeouts when viewing history
  • Charts fail to render

Diagnostic Steps:

  1. Check browser network tab:

    • Identify slow API calls
    • Look for failed requests
    • Monitor request timing

  2. Database performance:

    • Check database file size and location
    • Monitor disk I/O during queries
    • Review query complexity

Common Solutions:

Large Dataset Issues

  • Use rollup data for historical queries
  • Limit date ranges for raw data
  • Export large datasets instead of viewing online

Browser Performance

  • Use modern browser with good JavaScript performance
  • Close unnecessary browser tabs
  • Clear browser cache regularly

Network Latency

  • Access dashboard from local network
  • Check network connectivity quality
  • Consider browser-based performance tools

Data and Database Issues​

Missing Historical Data​

Symptoms:

  • Gaps in historical charts
  • CSV exports are incomplete
  • Rollup data missing

Diagnostic Steps:

  1. Check data retention:

    • Raw data: 60 days maximum
    • Rollups: unlimited retention
    • Review prune job logs

  2. Verify rollup processing:

    C:\ProgramData\ThingConnect.Pulse\logs\pulse-[date].log

Common Solutions:

Data Outside Retention Period

  • Raw data older than 60 days is automatically deleted
  • Use rollup data for older analysis
  • Plan data retention policies accordingly

Rollup Processing Issues

  • Check rollup background service
  • Review logs for processing errors
  • Restart service to reset rollup jobs

Database Corruption

  • Check database file integrity
  • Consider database repair tools
  • Restore from backup if available

Incorrect Status Reporting​

Symptoms:

  • Devices show wrong status
  • Status doesn't match reality
  • Inconsistent endpoint states

Diagnostic Steps:

  1. Verify probe configuration:

    • Check target reachability manually
    • Verify probe types and parameters
    • Test with simple ping first

  2. Review flap damping:

    • Understand 2/2 threshold logic
    • Check for rapid status changes
    • Monitor recent check history

Common Solutions:

Probe Configuration Issues

  • Verify target addresses are correct
  • Check TCP port numbers
  • Validate HTTP paths and expected content

Network Intermittency

  • Increase timeout values
  • Extend probe intervals
  • Check network stability

Flap Damping Sensitivity

  • Understand that status changes require 2 consecutive results
  • Brief outages may not trigger status change
  • Review recent checks for actual probe results

Getting Additional Help​

Log File Analysis​

Key Log Locations:

C:\ProgramData\ThingConnect.Pulse\logs\
├── pulse-[date].log          # Main service logs
├── rollup-[date].log        # Rollup processing
└── probe-[date].log         # Probe execution details

Log Level Information:

  • ERROR: Critical issues requiring attention
  • WARN: Potential problems to investigate
  • INFO: Normal operation status
  • DEBUG: Detailed operation information

System Information Collection​

For Support Requests:

  1. Service status: sc query ThingConnectPulseSvc
  2. Recent logs: Last 50 lines from current log file
  3. Configuration: Current YAML configuration (sanitized)
  4. System info: Windows version, .NET version
  5. Network info: Basic network connectivity tests

Escalation Path​

Before Contacting Support:

  1. Check this troubleshooting guide
  2. Review service logs for errors
  3. Test basic connectivity manually
  4. Document specific error messages
  5. Note steps to reproduce the issue

When All Else Fails:

  • Document the issue with screenshots
  • Collect relevant log files
  • Note system configuration details
  • Contact support with detailed information

Next Steps​