Connection Issues

Last Updated: October 4, 2026 Estimated Reading Time: 6 minutes

Overview

This guide helps you find and fix ServiceNow connection problems in cmdbx. Most connection problems come from credentials, roles and ACLs, the instance URL, or the ServiceNow instance itself.

Quick Diagnosis

Test Your Connection

  1. Go to Settings > ServiceNow.
  2. Click Test Connection.
  3. Read the result. The error message gives specific guidance for most problems.

Always run Test Connection first. Then find the error in this guide.

Authentication Errors

Error: "Authentication failed"

Symptom: The connection test shows "401 Unauthorized" or "Authentication failed".

Cause 1: Invalid OAuth client credentials or unsupported grant

  1. Verify the client ID and client secret in ServiceNow's inbound OAuth application.
  2. Confirm the client credentials grant is enabled and the application maps to an active OAuth Application User.
  3. Check any configured scopes and the instance's API access policy.
  4. Enter the replacement credentials in Settings > ServiceNow, then test and save.

Cause 2: The mapped integration user is locked or inactive

Ask the ServiceNow administrator to check the application's user, its active/locked state, roles and ACLs. A successful human browser login does not test this machine identity's OAuth access.

Cause 3: A secret or application was revoked

Rotate the OAuth credentials in ServiceNow and save the replacement in CMDBx. Short-lived access tokens renew automatically; stored write credentials have a separate expiry shown in settings. OAuth token endpoint failures are reported without returning the endpoint's response body.

CMDBx human SAML/MFA and ServiceNow machine access are separate. Use an approved machine identity; do not disable human MFA to make a scheduled integration work.

Permission Errors

Error: "Insufficient permissions" or "Cannot access table"

Symptom: "403 Forbidden", "ACL Error", or "Table not accessible".

The service account must be able to read every table in the sync scope. This includes:

  • the cmdb_ci tables for the CI classes that you sync
  • cmdb_rel_ci and cmdb_rel_type for relationships
  • sys_user for owner and support contact references
  • the incident, change request, and task_ci tables, if Operational Context is on

To fix the problem:

  1. Examine the ACLs for the table in ServiceNow: System Security > Access Control (ACL).
  2. Give the service account the minimum roles that grant read access. See ServiceNow Setup.
  3. For custom CI classes, make sure that the custom tables grant read access to the same roles.
  4. Use System Web Services > REST API Explorer in ServiceNow to test a read of the table with the service account.

"Web service access only" accounts need their roles assigned directly on the user record. Do not rely on roles that the account inherits from a group.

Configuration Errors

Error: "Invalid instance URL"

Symptom: "Instance not found", "404 Not Found", or the URL does not save.

cmdbx accepts only HTTPS ServiceNow instance URLs:

  • Correct: https://yourinstance.service-now.com
  • Incorrect: http://yourinstance.service-now.com (must be HTTPS)
  • Incorrect: https://yourinstance.service-now.com/nav_to.do (no path)
  • Incorrect: an IP address, localhost, a non-default port, or a URL with a username or password in it

If your instance uses a custom domain, contact [email protected]. cmdbx must allow the host first.

If you use a developer instance, make sure that it is not hibernating. Log in to the ServiceNow UI to wake it, and test again.

Error: "Connection already exists"

Each environment must connect to a different ServiceNow instance URL. You cannot connect two environments to the same instance. Edit the existing connection instead.

Network Errors

Error: "Connection timeout"

Symptom: The connection test waits and then times out.

  1. Make sure that the instance is available. Visit https://status.servicenow.com.
  2. If your ServiceNow instance restricts inbound IP addresses, contact [email protected] for the current cmdbx source addresses. Do not use IP addresses from older documents.
  3. If your ServiceNow instance is reachable only through a VPN, cmdbx cannot connect to it. Contact [email protected] to discuss options.

ServiceNow Instance Issues

The Instance Is Down or in Maintenance

Symptom: The connection worked before, and now it fails every time.

  1. Visit https://status.servicenow.com and check your instance.
  2. Check whether ServiceNow is in a scheduled maintenance or upgrade window.
  3. Wait, and then test the connection again.

API Rate Limiting

Symptom: The connection test succeeds, but the sync fails with "429 Too Many Requests".

  1. Go to Settings > Sync Config and choose a less frequent sync schedule.
  2. Reduce the sync scope to the CI classes that you need.
  3. Ask your ServiceNow administrator whether other integrations use the same API capacity.

How to Get Help

Before You Contact Support

Collect this information:

  1. The exact error message from Test Connection.
  2. Your ServiceNow release.
  3. Your instance URL. You can remove the company name.
  4. The roles of the service account.
  5. Recent changes to ServiceNow or to your network.
  6. The recent job history from Settings > Sync Status.

Contact Support

Email: [email protected]

Support is available during business hours, Monday to Friday, excluding public holidays. Never send passwords, API keys, or other secrets.

Best Practices

  1. Use a service account. Do not use a personal account for the integration.
  2. Keep roles minimal. Give the account only the roles that it needs.
  3. Rotate credentials carefully. Update cmdbx immediately after you rotate the password.
  4. Test changes in development first.
  5. Subscribe to ServiceNow status notifications.
  6. Turn on sync failure alerts in Settings > Alerts.

Related Articles