Jira Service Management Troubleshooting

Authentication Issues#

API Token Authentication Failures (401 Unauthorized)#

Symptoms:

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

Common Causes and Solutions:

1. Invalid API Token

   # Test API token directly
   curl -X GET 'https://your-domain.atlassian.net/rest/api/3/myself' \
     -H 'Authorization: Basic BASE64_ENCODED_CREDENTIALS' \
     -H 'Content-Type: application/json'

   • Base64 encode: email:api_token

2. Token Expired or Revoked

   • API tokens can be revoked from Atlassian Account settings
   • Generate a new token at https://id.atlassian.com/manage-profile/security/api-tokens

3. Wrong Account Email

   • Ensure the email matches the Atlassian account that created the token
   • Check for typos in the JIRA_USERNAME environment variable

Permission Errors (403 Forbidden)#

Symptoms:

• Can authenticate but cannot create/update issues
• Logs show PERMISSION_DENIED errors

Solutions:

1. Project Access

   • Verify the user has access to the target project
   • Check project permissions in Jira: Project Settings → Permissions

2. Issue Type Permissions

   • Ensure the “Incident” issue type exists in the project
   • User must have “Create Issues” permission for that type

Webhook Issues#

Webhooks Not Received#

Symptoms:

• Jira shows webhook deliveries succeeded
• No events appear in the platform timeline

Debugging Steps:

1. Check Webhook URL

   # Test endpoint accessibility
   curl -X POST https://your-domain/webhooks/jira \
     -H "Content-Type: application/json" \
     -d '{}'
   # Should return 401 (not 404 or timeout)

2. Verify Webhook Configuration in Jira

   • Go to: System → Webhooks
   • Ensure the URL is correct and SSL is valid
   • Check that required events are selected (issue_created, issue_updated)

3. Check JQL Filter

   • If using a JQL filter, verify it matches the target issues
   • Test the JQL in Jira’s issue search

Webhook Signature Validation Failures#

Symptoms:

• Webhooks return HTTP 401
• Logs show INVALID_WEBHOOK_SIGNATURE

Solutions:

1. Verify Shared Secret

   ./im connector jira status
   # Check webhook_secret is configured

2. Secret Mismatch

   • Re-copy the secret from Jira webhook configuration
   • Ensure no whitespace was accidentally included

Sync Issues#

Incidents Not Syncing to Jira#

Symptoms:

• Platform incidents don’t create Jira issues
• No outbound sync activity in logs

Debugging:

1. Check Connector Configuration

   ./im connector jira status
   # Verify sync_enabled: true

2. Check Field Mappings

   • Required Jira fields must have mappings configured
   • Custom fields need their IDs specified

3. Check Issue Type

   # List available issue types
   ./im connector jira list-issue-types --project ITSM

Field Mapping Errors#

Symptoms:

• Sync fails with “Field not found” errors
• Custom fields not populated correctly

Solutions:

1. Find Custom Field IDs

   curl -X GET 'https://your-domain.atlassian.net/rest/api/3/field' \
     -H 'Authorization: Basic BASE64_CREDENTIALS' \
     | jq '.[] | select(.name | contains("Severity"))'

2. Update Field Mappings

   • Custom fields use format: customfield_10001
   • Standard fields use names: summary, description, priority

Status Transitions Failing#

Symptoms:

• Status updates don’t sync correctly
• Logs show “Invalid transition” errors

Solutions:

1. Check Available Transitions

   # List transitions for an issue
   curl -X GET 'https://your-domain.atlassian.net/rest/api/3/issue/ITSM-123/transitions' \
     -H 'Authorization: Basic BASE64_CREDENTIALS'

2. Workflow Permissions

   • Some transitions require specific conditions
   • Check Jira workflow for required fields or permissions

Metrics and Observability#

Jira Integration Metrics#

The integration exposes these Prometheus metrics:

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

Enable Debug Logging#

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

Rate Limiting#

Hitting API Rate Limits (429)#

Symptoms:

• Requests fail with HTTP 429 Too Many Requests
• Sync slows down significantly

Solutions:

1. Check Current Usage

   • Jira Cloud: Check response headers for X-RateLimit-Remaining

2. Reduce Sync Frequency

   ./im connector jira configure --sync-interval 60s

3. Batch Operations

   • Use bulk update APIs where available
   • Queue non-urgent updates for batch processing

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 stack traces
   • Jira configuration (redact credentials!)
   • Steps to reproduce