Troubleshooting Guide

Common issues and solutions.

Table of contents

1. Connection Issues
   1. Perforce Connection Failed
   2. Jenkins Connection Failed
   3. Steam API Errors
2. Webhook Issues
   1. Webhooks Not Received
   2. Webhook Processing Failed
3. Build Issues
   1. Builds Not Triggering
   2. Build Status Not Updating
4. Notification Issues
   1. Discord/Slack Messages Not Sending
5. Data Issues
   1. Assets Not Linking
   2. Task References Not Working
6. Performance Issues
   1. Slow Sync
   2. High Memory Usage
7. Getting Help

Connection Issues

Perforce Connection Failed

Symptoms: Integration shows “Unhealthy” status, changelists not syncing.

Solutions:

1. Verify server URL format: ssl:server:1666 or server:1666
2. Check credentials are correct
3. Ensure ButterStack can reach the Perforce server (firewall, VPN)
4. Test connection manually: p4 -p server:1666 info

Jenkins Connection Failed

Symptoms: Cannot list jobs, builds not triggering.

Solutions:

1. Regenerate API token in Jenkins
2. Verify URL includes protocol: https://jenkins.example.com
3. Check user has permission to access jobs
4. Test API manually: curl -u user:token https://jenkins/api/json

Steam API Errors

Symptoms: Deployment status not updating.

Solutions:

1. Verify Publisher Key (not regular Steam API key)
2. Check App ID is correct
3. Ensure account has access to the app
4. Steam API rate limits - increase poll interval

Webhook Issues

Webhooks Not Received

Symptoms: Events not appearing in ButterStack.

Solutions:

1. Verify webhook URL is correct
2. Check webhook token matches integration settings
3. Ensure source system can reach ButterStack (firewall)
4. Review webhook logs in integration settings
5. Test with curl:

   curl -X POST "https://your-butterstack.com/webhooks/perforce?token=TOKEN" \
     -d "changelist=12345"
   

Webhook Processing Failed

Symptoms: Events received but showing as failed.

Solutions:

1. Check event payload format
2. Review error message in webhook logs
3. Verify related entities exist (project, integration)

Build Issues

Builds Not Triggering

Symptoms: Commits with #ci not starting builds.

Solutions:

1. Verify Jenkins integration is connected
2. Check default job is configured
3. Ensure job allows remote triggering
4. Review trigger tags: #ci, #build, #jenkins

Build Status Not Updating

Symptoms: Builds stuck in “In Progress”.

Solutions:

1. Verify Jenkins webhook is configured
2. Check webhook URL in Jenkins job
3. Ensure Notification plugin is installed
4. Review Jenkins console for webhook errors

Notification Issues

Discord/Slack Messages Not Sending

Symptoms: No notifications appearing.

Solutions:

1. Test webhook URL directly in Discord/Slack settings
2. Verify webhook hasn’t been deleted
3. Check notification preferences are enabled
4. Review rate limits (Discord: 30/min)

Data Issues

Assets Not Linking

Symptoms: Assets not appearing in lineage.

Solutions:

1. Verify file paths match between commits and assets
2. Check asset tracking is enabled for file type
3. Ensure project paths are configured correctly

Task References Not Working

Symptoms: Tasks not linking to commits.

Solutions:

1. Verify task key format: PROJ-123
2. Check task management integration is connected
3. Ensure task exists in the connected project

Performance Issues

Slow Sync

Symptoms: Long delays in data appearing.

Solutions:

1. Check webhook delivery (faster than polling)
2. Review queue status in ButterStack
3. Consider increasing resources if self-hosted

High Memory Usage

Symptoms: Application slowdown.

Solutions:

1. Archive old build data
2. Review ClickHouse retention settings
3. Check for runaway background jobs

Getting Help

If you can’t resolve an issue:

1. Check webhook logs for error details
2. Review integration health status
3. Contact support@butterstack.com with:
   • Integration type
   • Error messages
   • Steps to reproduce