ServiceNow Troubleshooting

Authentication Issues#

Basic Auth Failures (401 Unauthorized)#

Symptoms:

• Connector tests return HTTP 401 Unauthorized
• Logs show AUTHENTICATION_FAILED errors

Common Causes and Solutions:

1. Invalid Credentials

   # Test credentials directly
   curl -X GET 'https://dev12345.service-now.com/api/now/table/incident?sysparm_limit=1' \
     -u 'username:password' \
     -H 'Accept: application/json'

2. Account Locked

   • Too many failed attempts can lock the account
   • Check System Security → User Administration → Users

3. Password Policy

   • Some instances require periodic password changes
   • Service accounts may need exemptions from password policies

OAuth2 Token Issues#

Symptoms:

• Token refresh fails
• INVALID_GRANT or EXPIRED_TOKEN errors

Solutions:

1. Regenerate Client Credentials

   • Navigate to: System OAuth → Application Registry
   • Generate new client secret

2. Check Redirect URI

   • Must exactly match configured callback URL
   • Protocol, domain, and path must all match

3. Token Lifetime

   # Check token expiry
   ./im connector servicenow token-status

Connection Issues#

Instance Not Reachable#

Symptoms:

• Connection timeout errors
• DNS resolution failures

Debugging Steps:

1. Check Instance URL

   # Verify instance is accessible
   curl -I https://dev12345.service-now.com

2. Instance Hibernation (Developer Instances)

   • ServiceNow developer instances hibernate after inactivity
   • Log into the instance UI to wake it up
   • Consider upgrading to a non-hibernating instance for production

3. IP Allowlist

   • Some instances restrict API access by IP
   • Check: System Properties → Security → IP Address Access Control

SSL/TLS Errors#

Symptoms:

• SSL certificate verify failed errors
• unable to get local issuer certificate

Solutions:

1. Certificate Validation

   # Check certificate chain
   openssl s_client -connect dev12345.service-now.com:443 -showcerts

2. Corporate Proxy Issues

   • Proxies may inject their own certificates
   • Configure the platform to trust your CA bundle

Sync Issues#

Incidents Not Creating in ServiceNow#

Symptoms:

• Platform incidents don’t appear in ServiceNow
• No outbound sync in logs

Debugging:

1. Check Table API Access

   # Verify user can create incidents
   curl -X POST 'https://dev12345.service-now.com/api/now/table/incident' \
     -u 'username:password' \
     -H 'Content-Type: application/json' \
     -d '{"short_description": "Test incident"}'

2. Check User Roles

   • User needs itil or incident_manager role
   • Navigate to: User Administration → Users → [user] → Roles

3. Business Rules

   • Custom business rules may block incident creation
   • Check: System Definition → Business Rules

Field Mapping Errors#

Symptoms:

• Sync fails with “Unknown column” errors
• Custom fields not populated

Solutions:

1. Find Field Names

   # List incident table columns
   curl -X GET 'https://dev12345.service-now.com/api/now/table/sys_dictionary?sysparm_query=name=incident' \
     -u 'username:password' \
     -H 'Accept: application/json'

2. Custom Field Names

   • ServiceNow custom fields use u_ prefix (e.g., u_custom_field)
   • Check table structure in: System Definition → Tables → incident

Bidirectional Sync Conflicts#

Symptoms:

• Updates ping-pong between systems
• Unexpected field overwrites

Solutions:

1. Configure Field Ownership

   # In connector config
   field_ownership:
     severity: platform # Platform is authoritative
     state: servicenow # ServiceNow is authoritative

2. Use Change Detection

   • Enable timestamp-based conflict detection
   • Most recent update wins with audit trail

3. Check Update Timestamps

   ./im incident show INC-123 --show-sync-status

API Rate Limiting#

Hitting Concurrent Request Limits#

Symptoms:

• HTTP 429 Too Many Requests
• Exceeded maximum concurrent requests errors

Solutions:

1. Check Rate Limit Settings

   • ServiceNow limits concurrent sessions per user
   • Check: System Properties → Outbound HTTP requests

2. Implement Request Queuing

   ./im connector servicenow configure --max-concurrent 5

3. Use Service Account

   • Dedicated service accounts have separate limits
   • Avoid sharing credentials with interactive users

API Quota Exhausted#

Symptoms:

• Requests fail with quota errors
• Sync stops completely

Solutions:

1. Check API Usage

   • Navigate to: System Diagnostics → Stats → REST API Usage

2. Optimize Sync Frequency

   ./im connector servicenow configure --sync-interval 120s

Metrics and Observability#

ServiceNow Integration Metrics#

# Query metrics
curl -s http://localhost:9090/metrics | grep servicenow_

Enable Debug Logging#

export LOG_LEVEL=debug
export SERVICENOW_DEBUG=true
./im serve

Tracing API Calls#

Look for trace IDs in logs to track request flow:

trace_id=abc123 span_id=def456 servicenow.incident_number=INC0012345

Common Error Codes#

Getting Help#

If issues persist:

1. Enable debug logging and collect relevant log sections
2. Check the GitHub Issues for similar problems
3. Open a new issue with:
   • Error messages and ServiceNow error codes
   • Configuration (redact credentials!)
   • Instance version and type (Developer, Enterprise, etc.)