Troubleshooting Connection Issues

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

Overview

This guide helps you diagnose and resolve ServiceNow connection issues in cmdbx. Most connection problems fall into one of five categories: authentication, network, permissions, configuration, or ServiceNow instance issues.

Quick Diagnosis

Test Your Connection

  1. Navigate to Settings > Connection
  2. Click Test Connection
  3. Review the result:
    • Success: Connection working
    • Authentication Failed: Credentials issue
    • Connection Timeout: Network issue
    • Insufficient Permissions: Role issue
    • Instance Not Found: URL issue

Always run "Test Connection" first. The error message provides specific guidance for most common issues.

Authentication Errors

Error: "Authentication failed"

Symptom: Connection test shows "401 Unauthorized" or "Authentication failed"

Common Causes:

1. Incorrect Username or Password

Solution:

  1. Verify credentials in ServiceNow:
    • Log into ServiceNow UI with same credentials
    • If login fails, reset password in ServiceNow
  2. Update credentials in cmdbx:
    • Settings > Connection → Edit Connection
    • Re-enter username and password
    • Save and test

2. Account Locked or Disabled

Solution:

  1. In ServiceNow, navigate to User Administration → Users
  2. Search for service account
  3. Check:
    • Active: Must be checked
    • Locked out: Must be unchecked
    • Account enabled: Yes
  4. If locked, click Unlock Account
  5. Test connection in cmdbx

3. Password Expired

Solution:

  1. In ServiceNow, check password expiration date
  2. If expired:
    • Reset password
    • Update in cmdbx
    • Consider enabling "Password never expires" for service accounts
  3. Test connection

4. OAuth Token Expired (if using OAuth)

Solution:

  1. Settings > Connection → OAuth Settings
  2. Click Refresh Token
  3. If refresh fails, regenerate OAuth credentials:
    • In ServiceNow: System OAuth → Application Registry
    • Edit cmdbx application
    • Generate new client secret
    • Update in cmdbx
  4. Test connection

For service accounts, enable "Password never expires" to prevent unexpected authentication failures. Rotate credentials manually on a schedule instead.

Error: "Invalid OAuth configuration"

Symptom: OAuth authentication failing

Solution:

  1. Verify OAuth Settings in ServiceNow:

    • Navigate to System OAuth → Application Registry
    • Find cmdbx application
    • Check:
      • Client ID matches cmdbx configuration
      • Redirect URL is correct: https://app.cmdbx.com/api/auth/callback
      • Token expiration settings are reasonable

  2. Regenerate OAuth Credentials:

    • In ServiceNow OAuth app, click Regenerate Secret
    • Copy new Client ID and Secret
    • In cmdbx: Settings > Connection
    • Enter new credentials
    • Save and test

  3. Check OAuth Scopes:

    • Ensure OAuth app has access to CMDB tables
    • Grant useraccount scope

Network Errors

Error: "Connection timeout"

Symptom: Test connection hangs then times out after 30 seconds

Common Causes:

1. Firewall Blocking cmdbx

Solution:

  1. Check if your firewall blocks outbound connections from ServiceNow
  2. Whitelist cmdbx IP addresses in your firewall:
    • 52.87.143.22
    • 54.165.201.89
    • 34.201.45.123
  3. Contact your network team if needed
  4. Test connection

2. ServiceNow IP Whitelist Blocking cmdbx

Solution:

  1. In ServiceNow: System Security → IP Address Access Control
  2. Check if IP restrictions are enabled
  3. Add cmdbx IP addresses:
    • Create new rule for each IP
    • Type: Allow
    • IP Address: (enter cmdbx IP)
  4. Save
  5. Test connection

3. Corporate Proxy

Solution:

  1. If ServiceNow is behind corporate proxy:
    • Settings > Connection → Advanced
    • Enable Use Proxy
    • Enter proxy details:
      • Host: proxy.yourcompany.com
      • Port: 8080
      • Username/Password (if required)
  2. Save and test

4. VPN Required

Solution:

  • If ServiceNow only accessible via VPN, cmdbx cannot connect
  • Options:
    • Configure ServiceNow to allow connections from cmdbx IPs
    • Use a private or dedicated deployment model if required
    • Set up site-to-site connectivity as part of an Enterprise or MSP engagement

Error: "SSL certificate error"

Symptom: "SSL certificate verification failed" or "Certificate invalid"

Solution:

  1. Self-Signed Certificate:

    • ServiceNow production instances should use valid SSL certificates
    • For dev instances with self-signed certs:
      • Settings > Connection → Advanced
      • Enable Allow Self-Signed Certificates (not recommended for production)
    • Better: Install valid certificate on ServiceNow instance

  2. Expired Certificate:

    • Check ServiceNow certificate expiration
    • Renew certificate in ServiceNow
    • Test connection

  3. Hostname Mismatch:

    • Ensure ServiceNow URL matches certificate common name
    • Use correct instance URL (no trailing slash)

Permission Errors

Error: "Insufficient permissions"

Symptom: "403 Forbidden" or "User lacks required roles"

Solution:

  1. Check Required Roles:

    • Service account needs:
      • itil role
      • cmdb_read role (minimum)
      • cmdb_write role (if using CSDM Workbench)
      • cmdb_admin role (for service modeling)

  2. Assign Roles in ServiceNow:

    • Navigate to User Administration → Users
    • Find service account
    • Scroll to Roles section
    • Click Edit
    • Add missing roles
    • Save

  3. Verify Role Assignment:

    • In ServiceNow, navigate to System Web Services → REST API Explorer
    • Test API call to cmdb_ci_server table
    • If succeeds: cmdbx should work
    • If fails: Role assignment issue

"Web Service Access Only" accounts need roles assigned at the user level, not inherited from groups. Directly assign roles to the service account.

Error: "Cannot access table"

Symptom: "ACL Error" or "Table not accessible"

Solution:

  1. Check Table ACLs:

    • In ServiceNow: System Security → Access Control (ACL)
    • Search for CMDB table (e.g., cmdb_ci_server)
    • Verify service account's roles grant read access
    • Add role to ACL if needed

  2. Custom CI Classes:

    • If syncing custom CI classes:
      • Verify service account has read access to custom tables
      • Check if custom tables inherit CMDB ACLs
      • Grant specific access if needed

Configuration Errors

Error: "Invalid instance URL"

Symptom: "Instance not found" or "404 Not Found"

Solution:

  1. Verify URL Format:

    • Correct: https://yourinstance.service-now.com
    • Wrong: http://yourinstance.service-now.com (no HTTP, must be HTTPS)
    • Wrong: https://yourinstance.service-now.com/ (no trailing slash)
    • Wrong: https://yourinstance.service-now.com/nav_to.do (no path)

  2. Check Instance Name:

    • Ensure instance name is correct
    • Dev instances: https://dev12345.service-now.com
    • Production: https://yourcompany.service-now.com

  3. ServiceNow Instance Active:

    • Verify instance is not hibernated (dev instances hibernate if inactive)
    • Log into ServiceNow UI to wake up instance
    • Test cmdbx connection again

Error: "Connection already exists"

Symptom: Cannot create new connection

Solution:

  1. Check if connection to same instance URL already exists
  2. Either:
    • Edit existing connection instead of creating new
    • Delete old connection (if truly duplicate)
  3. Note: Same instance URL cannot be used for multiple environments

ServiceNow Instance Issues

ServiceNow Instance Down

Symptom: Connection worked before, now fails consistently

Solution:

  1. Check ServiceNow Status:

    • Visit https://status.servicenow.com
    • Check if your instance/region has issues
    • Wait for ServiceNow to resolve

  2. Maintenance Window:

    • Check if ServiceNow is in scheduled maintenance
    • ServiceNow upgrade windows typically 2-4 hours
    • Wait and retry after maintenance

  3. Instance Hibernation (Dev instances):

    • Dev instances hibernate after 7 days inactivity
    • Log into ServiceNow UI to wake instance
    • Takes 2-3 minutes to wake
    • Retry cmdbx connection

API Rate Limiting

Symptom: Connection succeeds but sync fails with "429 Too Many Requests"

Solution:

  1. Reduce Sync Frequency:

    • Settings > Sync Config
    • Change from hourly to daily
    • Reduce parallel threads from 5 to 3

  2. Reduce Batch Size:

    • Settings > Sync Config → Advanced
    • Reduce batch size from 1000 to 500

  3. Contact ServiceNow Admin:

    • Request increased API rate limits
    • Verify no other integrations exhausting API quota

  4. Review ServiceNow API Entitlements:

    • Some ServiceNow editions have lower API limits
    • Confirm your current quota and raise limits if needed

Advanced Troubleshooting

Enable Debug Logging

For persistent issues:

  1. Navigate to Settings > Connection → Advanced
  2. Enable Debug Logging
  3. Set Log Level: Verbose
  4. Test connection
  5. View logs: Settings > Sync Status → Connection Logs
  6. Look for detailed error messages
  7. Share logs with [email protected] if needed

Test with cURL

Test connection outside cmdbx:

curl -X GET \
  'https://yourinstance.service-now.com/api/now/table/cmdb_ci_server?sysparm_limit=1' \
  -H 'Accept: application/json' \
  -u 'username:password'

Expected: 200 OK with JSON data

If fails: Issue is with ServiceNow configuration, not cmdbx

ServiceNow REST API Explorer

Test credentials in ServiceNow:

  1. In ServiceNow: System Web Services → REST API Explorer
  2. Select API: Table API
  3. Select Method: Retrieve records from a table
  4. Set Table: cmdb_ci_server
  5. Set sysparm_limit: 1
  6. Click Send
  7. Verify 200 OK response

If this fails, credentials/permissions are the issue.

Getting Help

Before Contacting Support

Gather this information:

  1. Error Message: Exact text from "Test Connection"
  2. ServiceNow Version: Help → About ServiceNow
  3. Instance URL: (you can redact company name)
  4. Roles Assigned: Screenshot of service account roles
  5. Recent Changes: Any changes to ServiceNow or network
  6. Connection Logs: Settings > Sync Status → Connection Logs (last 24 hours)

Contact Support

Email: [email protected]

Include:

  • Tenant ID
  • Environment name
  • Error details above
  • Best time to contact you

Response Time:

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

Prevention

Monitoring Connection Health

  1. Enable Connection Monitoring:

    • Settings > Connection → Monitoring
    • Enable Connection Health Checks
    • Frequency: Every 15 minutes

  2. Set Up Alerts:

    • Settings > Connection → Notifications
    • Enable Connection Failure Alert
    • Recipients: CMDB Admins
    • Email immediately on failure

  3. Review Connection Logs:

    • Weekly review of connection logs
    • Investigate any failures
    • Address issues proactively

Best Practices

  1. Use Service Account: Never use personal accounts for integration
  2. Document Configuration: Keep record of settings
  3. Test Changes: Test in dev before production
  4. Monitor ServiceNow Status: Subscribe to status.servicenow.com
  5. Coordinate Upgrades: Plan cmdbx maintenance with ServiceNow upgrades
  6. Rotate Credentials Carefully: Update cmdbx immediately after rotation
  7. Keep Roles Minimal: Only assign required roles, no more

Related Articles

Need Help?

Contact [email protected] with error details and we'll help resolve your connection issue.