Troubleshooting Guide

Common issues and solutions for ButterStack integrations

Common Issues

Connection Issues

Jenkins Not Responding

Solution Steps:

1. Verify Jenkins URL

   curl -I https://your-jenkins.com/api/json
   

2. Check API Token
   • Navigate to Jenkins → User → Configure
   • Generate new API token if needed
3. Test Connection

   # In Rails console
   integration = Integration.find_by(platform: 'jenkins')
   client = Integrations::JenkinsClient.new(integration)
   client.test_connection
   

Perforce Connection Timeout

Debugging Steps:

# Test P4 connection
p4 -p ssl:perforce.company.com:1666 info

# Check environment
echo $P4PORT
echo $P4USER

Authentication Errors

Invalid API Key

Quick Fixes by Platform:

Jira

# Test Jira API key
curl -u email@company.com:API_TOKEN \
  https://company.atlassian.net/rest/api/3/myself

Linear

# Test Linear API key
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.linear.app/graphql \
  -d '{"query":"{ viewer { id name } }"}'

Slack

# Test Slack webhook
curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Test message"}' \
  YOUR_WEBHOOK_URL

OAuth Token Expired

Refresh OAuth Tokens:

# In Rails console
account = Account.find(id)
connected_account = account.connected_accounts.find_by(provider: 'github')
connected_account.refresh_token!

Webhook Failures

Webhooks Not Received

Debugging Checklist:

• Webhook URL is publicly accessible
• SSL certificate is valid
• Webhook secret matches configuration
• Request payload size < 10MB
• Response time < 30 seconds

Event Processing Errors

# Check recent webhook logs
InboundWebhook.where(status: 'error')
  .where('created_at > ?', 1.hour.ago)
  .pluck(:error_message)

Performance Issues

Slow Asset Analysis

Optimization Tips:

1. Reduce File Size

   # Compress textures before upload
   convert input.png -quality 85 output.jpg
   

2. Batch Processing

   # Process multiple assets
   Asset.pending_analysis.find_in_batches(batch_size: 10) do |batch|
     batch.each { |asset| AssetAnalysisWorker.perform_async(asset.id) }
   end
   

3. Check Queue Status

   # Monitor Sidekiq queues
   bundle exec sidekiq-status
   

Error Reference

Common Error Codes

Integration-Specific Errors

Getting Help

Support Channels

Debug Information to Include

When contacting support, include:

# System information
rails runner "puts Integration.debug_info"

# Recent errors
tail -n 100 log/production.log | grep ERROR

# Integration status
rails c
Integration.all.map { |i| [i.name, i.status, i.last_sync_at] }