Troubleshooting Sync Problems

Last Updated: January 7, 2026 Estimated Reading Time: 8 minutes

Overview

This guide helps you diagnose and fix data synchronization issues between ServiceNow and cmdbx. Sync problems typically manifest as missing data, stale data, sync failures, or slow sync performance.

Quick Diagnosis

Check Sync Status

  1. Navigate to Settings > Sync Config → Status

  2. Review:

    • Last Sync: When it completed
    • Status: Success, Failed, In Progress, or Pending
    • CIs Synced: Number of CIs imported
    • Errors: Error count and types
    • Duration: How long sync took

  3. If sync failed, click View Logs for detailed error messages

Check sync logs first. They contain specific error messages that indicate the root cause 90% of the time.

Sync Failures

Error: "Sync failed - Authentication error"

Symptom: Sync starts but immediately fails with authentication error

Cause: ServiceNow credentials expired or changed

Solution:

  1. Navigate to Settings > Connection
  2. Click Test Connection
  3. If connection fails:
    • Verify credentials in ServiceNow
    • Update credentials in cmdbx
    • Re-test connection
  4. If connection succeeds but sync fails:
    • Check if service account password was recently changed
    • Verify roles are still assigned
    • Test API access in ServiceNow REST API Explorer

See Connection Issues for detailed authentication troubleshooting.

Error: "Sync timeout"

Symptom: Sync runs for hours then times out

Common Causes:

1. Too Many CIs to Sync

Solution:

  1. Navigate to Settings > Sync Config → Data Scope
  2. Reduce scope:
    • Uncheck unnecessary CI classes
    • Add environment filter (production only)
    • Exclude decommissioned CIs: operational_status!=6
  3. Run Test Sync with smaller scope
  4. If succeeds, gradually expand scope

2. ServiceNow Performance Issues

Solution:

  1. Check ServiceNow instance performance
  2. Schedule sync during off-peak hours
  3. Increase sync timeout:
    • Settings > Sync Config → Advanced
    • Set Sync Timeout: 4 hours (default: 2 hours)
  4. Contact ServiceNow admin to optimize CMDB table indexes

3. Network Issues

Solution:

  1. Check for network connectivity problems
  2. Review connection logs for intermittent failures
  3. Enable retry on failure:
    • Settings > Sync Config → Advanced
    • Enable Retry Failed Batches
    • Set Max Retries: 3

Error: "Insufficient API quota"

Symptom: Sync fails with "429 Too Many Requests" or "API rate limit exceeded"

Solution:

1. Reduce API Call Rate:

  1. Navigate to Settings > Sync Config → Advanced
  2. Reduce Max Requests/Second: From 10 to 5
  3. Reduce Parallel Threads: From 5 to 3
  4. Increase Batch Size: From 1000 to 2000 (fewer API calls)
  5. Save and retry sync

2. Schedule Sync During Off-Peak:

  1. Avoid syncing when other integrations are active
  2. Schedule for early morning hours
  3. Coordinate with ServiceNow admin

3. Request Higher Quota:

  1. Contact ServiceNow admin
  2. Request increased API rate limit
  3. Verify no other integrations exhausting quota
  4. Consider upgrading ServiceNow edition

4. Use Incremental Sync:

  1. Switch from full sync to incremental
  2. Incremental sync uses 90% fewer API calls
  3. Schedule full sync weekly instead of daily

Incremental syncs are much faster and use fewer API calls. Use full syncs only weekly or monthly for data integrity checks.

Error: "Relationship sync failed"

Symptom: CIs sync successfully but relationships missing

Common Causes:

1. Missing Related CIs

Solution:

  • Relationship can't be created if either end doesn't exist
  • Ensure both CIs are included in sync scope
  • Check sync logs for "Skipped relationship: CI not found" messages
  • Expand sync scope to include missing CI classes

2. Invalid Relationship Data

Solution:

  1. Review sync logs for specific relationship errors
  2. Common issues:
    • Self-referencing relationships (CI relates to itself)
    • Circular dependencies
    • Deleted CIs still referenced
  3. Fix in ServiceNow:
    • Remove invalid relationships
    • Update or delete stale relationships
  4. Resync

3. Relationship Type Not Synced

Solution:

  1. Navigate to Settings > Sync Config → Data Scope → Relationships
  2. Verify relationship types are checked:
    • Runs on::Runs on
    • Depends on::Used by
    • Contains::Contained by
  3. Add missing relationship types
  4. Resync

Missing Data

CIs Not Syncing

Symptom: Specific CIs exist in ServiceNow but not in cmdbx

Troubleshooting Steps:

1. Check CI Class Filter:

  1. Navigate to Settings > Sync Config → Data Scope → CI Classes
  2. Verify CI class is checked
  3. If not, check it and resync

2. Check Environment Filter:

  1. Navigate to Settings > Sync Config → Data Scope → Filters
  2. Review custom filters (e.g., operational_status=1)
  3. Test if missing CIs match filter:
    • In ServiceNow, query CIs with your filter
    • Verify missing CIs are included in results
  4. If filter excludes them, adjust filter

3. Check CI Permissions:

  1. Verify service account has read access to CI class
  2. In ServiceNow REST API Explorer:
    • Query the specific CI class
    • If 403 error, permission issue
  3. Assign appropriate role to service account

4. Check Sync Logs:

  1. Settings > Sync Config → Logs
  2. Search for CI sys_id or name
  3. Look for "Skipped" or "Error" entries
  4. Address specific error message

Data Not Updating

Symptom: Data exists but is stale (not reflecting ServiceNow changes)

Common Causes:

1. Incremental Sync Not Detecting Changes

Solution:

  1. Run manual full sync to force refresh:
    • Settings > Sync Config
    • Click Run Full Sync Now
  2. If data updates after full sync:

2. Sync Not Running

Solution:

  1. Verify sync schedule is enabled:
    • Settings > Sync Config → Schedule
    • Check Enabled is checked
  2. Check last sync time:
    • If no recent sync, schedule may be misconfigured
  3. Check sync logs for failures

3. ServiceNow Not Updating

Solution:

  1. Verify data is actually updated in ServiceNow
  2. Check CI's Updated timestamp in ServiceNow
  3. If ServiceNow data is also stale:
    • Issue is in ServiceNow, not cmdbx
    • Check ServiceNow discovery and integrations

Slow Sync Performance

Sync Taking Too Long

Symptom: Sync completes but takes hours

Optimization Steps:

1. Reduce Data Scope:

  • Sync only production environment
  • Exclude inactive/decommissioned CIs
  • Focus on critical CI classes first
  • Target: 10,000-30,000 CIs for best performance

2. Optimize Batch Size:

  1. Navigate to Settings > Sync Config → Advanced
  2. Test different batch sizes:
    • Small (500): Better for slow ServiceNow instances
    • Medium (1000): Default, good balance
    • Large (2000): Better for fast instances
  3. Monitor sync duration and adjust

3. Increase Parallelization:

  1. Increase Parallel Threads: From 5 to 10
  2. Monitor ServiceNow instance CPU usage
  3. If ServiceNow slows down, reduce threads
  4. Find optimal balance

4. Schedule During Off-Peak:

  1. Move sync to 1-5 AM when ServiceNow is idle
  2. Avoid business hours
  3. Coordinate with ServiceNow maintenance windows

5. Optimize Health Calculation:

  1. Disable health recalculation during sync:
    • Settings > Sync Config → Advanced
    • Uncheck Recalculate Health Scores After Sync
  2. Schedule separate health calculation job
  3. Reduces sync time by 30-50%

Performance Monitoring

Track These Metrics:

  1. Navigate to Settings > Sync Config → Performance
  2. Review:
    • Sync Duration Trend: Should be stable or improving
    • CIs Synced Per Minute: Target 500+ CIs/min
    • API Calls Per Sync: Should decrease with optimization
    • Error Rate: Target < 1%
    • Retry Rate: Target < 5%

Expected Performance:

| CMDB Size | Full Sync Duration | Incremental Sync | |-----------|-------------------|------------------| | 1,000 CIs | 2-5 minutes | 1-2 minutes | | 10,000 CIs | 20-30 minutes | 3-5 minutes | | 50,000 CIs | 1-2 hours | 10-15 minutes | | 100,000+ CIs | 3-4 hours | 20-30 minutes |

If your sync is significantly slower, optimization needed.

Health Score Issues

Health Scores Not Updating

Symptom: Sync succeeds but health scores remain unchanged

Solution:

1. Enable Health Recalculation:

  1. Navigate to Settings > Sync Config → Advanced
  2. Check Recalculate Health Scores After Sync
  3. Save and resync

2. Manual Health Recalculation:

  1. Navigate to CI Health Workspace
  2. Click Recalculate All Health Scores
  3. Monitor progress
  4. Verify scores update

3. Check Health Calculation Logs:

  1. Settings > Sync Status → Health Calculation
  2. Look for errors during calculation
  3. Address specific errors

Incorrect Health Scores

Symptom: Health scores seem wrong after sync

Solution:

  1. Verify Data Accuracy:

    • Check if CI data in cmdbx matches ServiceNow
    • Incorrect data = incorrect health scores
    • Investigate sync data quality issues

  2. Review Health Rules:

    • CI Health Workspace → Rules
    • Verify health calculation rules are appropriate
    • Check for custom rule misconfigurations

  3. Recalculate Health:

    • Force full health recalculation
    • CI Health Workspace → Recalculate All

See Health Score Questions for detailed health score troubleshooting.

CSDM Compliance Issues

CSDM Validation Failing

Symptom: Sync succeeds but CSDM compliance check fails

Solution:

  1. Run CSDM Validation Manually:

    • Navigate to CSDM Workbench
    • Click Run Compliance Check
    • Review specific violations

  2. Check Relationship Sync:

    • CSDM validation requires all relationships
    • Verify relationships synced correctly
    • Check sync logs for relationship errors

  3. Validate in ServiceNow:

    • Ensure ServiceNow data is CSDM compliant
    • cmdbx reflects ServiceNow data accurately
    • Fix violations in ServiceNow, then resync

See CSDM Compliance for guidance on achieving compliance.

Advanced Troubleshooting

Enable Debug Logging

For persistent issues:

  1. Navigate to Settings > Sync Config → Advanced
  2. Enable Debug Logging
  3. Set Log Level: Verbose
  4. Run sync
  5. Review detailed logs: Settings > Sync Status → Sync Logs
  6. Share with support if needed

Compare Sync Results

Verify cmdbx matches ServiceNow:

  1. Count CIs in ServiceNow:

    • Navigate to CMDB → CI Class Manager
    • Count CIs by class
    • Note totals

  2. Count CIs in cmdbx:

    • Navigate to CI Health Workspace
    • Filter by CI class
    • Note totals

  3. Compare:

    • Should match within 1-2%
    • If significant difference:
      • Check sync filters
      • Review sync logs for skipped CIs
      • Verify permissions

Test Sync Scope

Test with minimal scope:

  1. Create test sync configuration:
    • Only 1 CI class (e.g., servers)
    • Only 1 environment (production)
    • Limit 100 CIs: sysparm_limit=100
  2. Run test sync
  3. If succeeds: Gradually expand scope
  4. If fails: Issue with ServiceNow or connection

Getting Help

Before Contacting Support

Gather this information:

  1. Sync Logs: Last 24 hours from Settings > Sync Status → Sync Logs
  2. Error Messages: Exact error text
  3. Sync Configuration: Screenshot of sync settings
  4. Data Scope: CI classes and filters configured
  5. ServiceNow Version: Help → About ServiceNow
  6. CMDB Size: Approximate number of CIs
  7. When Did It Stop Working: Date/time of last successful sync

Contact Support

Email: [email protected]

Include:

  • Tenant ID
  • Environment name
  • Error details above
  • Urgency level

Response Time:

  • Professional: 48 hours
  • Business: 24 hours
  • Enterprise: 4 hours
  • MSP: Custom

Prevention

Monitoring Sync Health

Set Up Alerts:

  1. Navigate to Settings > Sync Config → Notifications
  2. Enable alerts for:
    • Sync Failures: Email immediately
    • Slow Syncs: Email if duration > 2x average
    • High Error Rate: Email if errors > 10%
  3. Set recipients: CMDB Admins

Weekly Review:

  1. Review sync logs weekly
  2. Check for patterns in errors
  3. Address issues before they escalate
  4. Optimize performance proactively

Best Practices

  1. Start Small: Begin with narrow scope, expand gradually
  2. Test Changes: Test sync configuration in dev before production
  3. Monitor Performance: Track sync duration trends
  4. Schedule Wisely: Run syncs during off-peak hours
  5. Incremental by Default: Use full sync only weekly/monthly
  6. Keep ServiceNow Healthy: Optimize ServiceNow CMDB for best sync performance
  7. Document Issues: Keep log of issues and resolutions
  8. Regular Audits: Compare cmdbx vs ServiceNow data quarterly

Related Articles

Need Help?

Contact [email protected] with sync logs and error details for assistance.