Troubleshooting

This guide helps you diagnose and resolve common issues with the Linear integration. Issues are organized by area for quick navigation.

Connection Issues

PagerDuty Connection Failed

Symptoms:

• OAuth authorization fails or times out
• Error message during connection attempt
• Redirected back to Integration Hub without successful connection

Solutions:

1. Verify Account Permissions
   • Check that you have Manager, Admin, or Global Admin role in PagerDuty
   • Confirm your account has Professional, Business, or Enterprise plan
2. Clear Browser State
   • Clear cookies and cache for Integration Hub domain
   • Try a different browser or incognito/private mode
3. Check PagerDuty Account
   • Verify you're logged into the correct PagerDuty account
   • Log out of PagerDuty and log back in
4. Retry Connection
   • Wait a few minutes and try connecting again
   • Check PagerDuty status page for service issues

Linear Connection Failed

Symptoms:

• OAuth authorization fails
• Error during Linear workspace selection
• Disconnected immediately after connecting

Solutions:

1. Verify Workspace Access
   • Check that you have Member or Admin role in Linear workspace
   • Confirm you selected the correct workspace during authorization
2. Check Permissions
   • Verify you can create webhooks in Linear (Settings → Webhooks)
   • Ensure you have access to teams you want to integrate
3. Clear Browser State
   • Clear cookies for both Integration Hub and Linear domains
   • Try a different browser
4. Verify Linear Account
   • Log into Linear directly to verify your account is active
   • Check if your workspace has any access restrictions

Connection Shows as Disconnected

Symptoms:

• Previously connected account now shows "Disconnected"
• Can't create webhooks or rules
• Sync stopped working

Solutions:

1. Check OAuth Token Status
   • OAuth tokens can expire or be revoked
   • Disconnect and reconnect to get a new token
2. Verify Account Access
   • Confirm you still have the required permissions
   • Check if your role changed in PagerDuty or Linear
3. Check for Revoked Access
   • PagerDuty: Settings → OAuth Applications
   • Linear: Settings → My Account → Applications
4. Reconnect
   • Click "Connect" button again to re-authorize

Webhook Issues

Can't Create Webhook

Symptoms:

• Webhook creation fails with error
• No teams appear in dropdown
• Error message about permissions

Solutions:

1. Verify Connections
   • Ensure both PagerDuty and Linear are connected
   • Check connection status shows "Connected"
2. Check Team Access
   • Verify you have access to Linear teams in the dropdown
   • Ask workspace admin to grant team access if needed
3. Avoid Duplicates
   • Check if webhook already exists for this team
   • You can only have one webhook per team
4. Verify Permissions
   • Confirm you can create webhooks in Linear manually
   • Check Linear Settings → Webhooks to verify webhook permissions

Webhook Shows as Inactive

Symptoms:

• Webhook status is "Inactive"
• Not receiving issue updates
• Rules not triggering

Solutions:

1. Check Linear Connection
   • Verify Linear connection is active
   • Reconnect if needed
2. Verify Webhook in Linear
   • Go to Linear Settings → Webhooks
   • Look for Integration Hub webhook
   • Check if webhook is enabled in Linear
3. Check Team Access
   • Verify you still have access to the team
   • Team may have been renamed or deleted
4. Recreate Webhook
   • Delete the inactive webhook
   • Create a new webhook for the same team

Webhook Not Receiving Updates

Symptoms:

• Webhook exists but rules aren't triggering
• Creating/updating Linear issues has no effect
• Webhook shows as "Active" but nothing happens

Solutions:

1. Test with Simple Issue
   • Create a new issue in Linear that should clearly match a rule
   • Use Urgent priority and Triage status for easiest testing
2. Check Rule Configuration
   • Verify you have at least one enabled rule using this webhook
   • Check that rule criteria aren't too restrictive
3. Verify Webhook Delivery
   • Check Linear Settings → Webhooks
   • Look at webhook delivery logs
   • Verify webhooks are being sent successfully
4. Check for Webhook Errors
   • Linear may disable webhooks after repeated failures
   • Look for error notifications in Linear
   • Recreate webhook if necessary

Rule Issues

Incidents Not Being Created

Symptoms:

• Linear issues that should match rules don't create incidents
• Rules appear configured correctly but nothing happens
• No errors shown

Solutions:

1. Verify Rule is Enabled
   • Check the enabled toggle switch on the rule
   • Disabled rules won't create incidents
2. Check All Filter Criteria
   • Issue must match ALL criteria (AND logic)
   • Priority: Does issue have selected priority?
   • Status: Is issue in selected status type?
   • Project: If project filter set, is issue in that project?
   • Labels: If label filter set, does issue have one of those labels?
3. Test with Minimal Filters
   • Temporarily simplify rule (e.g., only Urgent priority, any status)
   • Create test issue that clearly matches
   • Gradually add back filters to identify problem
4. Verify Webhook is Active
   • Check that the webhook used by this rule is active
   • Webhook must be receiving events for rules to work
5. Check PagerDuty Service
   • Verify the PagerDuty service still exists
   • Check that you have permission to create incidents for this service

Duplicate Incidents Created

Symptoms:

• Multiple incidents created for same Linear issue
• Incidents in different services for same issue

Solutions:

1. Check for Overlapping Rules
   • Review all rules for the same webhook
   • Look for rules with similar or overlapping criteria
   • Example: Two rules both monitoring "Urgent" priority
2. Use More Specific Filters
   • Add project or label filters to differentiate rules
   • Make rules mutually exclusive
3. Consolidate Rules
   • If two rules route to same service, combine them
   • Use one rule with multiple priority or status selections
4. Disable or Delete Duplicate Rules
   • Keep only the rule you want to use

Wrong Service Receiving Incidents

Symptoms:

• Incidents created in unexpected PagerDuty service
• On-call team doesn't match issue type

Solutions:

1. Review Rule Configuration
   • Open the rule and check selected PagerDuty service
   • Verify it matches your intended service
2. Check for Multiple Rules
   • Multiple rules might be matching the same issue
   • Look for overlapping criteria across rules
3. Edit Rule
   • Update rule to use correct PagerDuty service
   • Save changes and test with new issue

Bidirectional Sync Issues

PagerDuty Ack/Resolve Not Updating Linear

Symptoms:

• Acknowledging incident in PagerDuty doesn't update Linear issue
• Resolving incident doesn't move issue to done status
• Status mapping not working

Solutions:

1. Verify Status Mappings Configured
   • Open rule and check "Acknowledged Status" field
   • Check "Resolved Status" field
   • Both must be set for sync to work
2. Check PagerDuty Webhook
   • Go to PagerDuty service → Integrations
   • Look for Integration Hub webhook
   • Webhook should exist and be enabled
3. Verify Linear Connection
   • Check Linear connection status is "Connected"
   • Reconnect if needed
4. Check Linear Issue Exists
   • Verify issue still exists and isn't archived
   • Confirm you have permission to update the issue
5. Test with New Incident
   • Create new issue that creates incident
   • Acknowledge new incident
   • Check if status updates
   • If working for new incidents, old incident may have issue

PagerDuty Notes Not Syncing to Linear

Symptoms:

• Notes added in PagerDuty don't appear as Linear comments
• Some notes sync but others don't

Solutions:

1. Verify Linear Connection
   • Check connection status is "Connected"
   • Reconnect if disconnected
2. Check Permissions
   • Verify you can comment on Linear issues
   • Issue may be locked or archived
3. Verify PagerDuty Webhook
   • Check webhook exists for the service
   • Webhook must be enabled
4. Try New Note
   • Add a new note to the incident
   • Wait 5-10 seconds
   • Refresh Linear issue to see if comment appears

Linear "Done" Not Resolving PagerDuty Incident

Symptoms:

• Marking Linear issue as done/completed doesn't resolve incident
• Canceled issues don't resolve incident

Solutions:

1. Verify Status Type
   • Only status TYPES "Completed" or "Canceled" resolve incidents
   • Check status type in Linear Settings → Workflow States
   • Status name doesn't matter, only the type
2. Check Webhook is Active
   • Linear webhook must be active to send updates
   • Verify webhook status in Integration Hub
3. Verify PagerDuty Connection
   • Check PagerDuty connection is active
   • Reconnect if needed
4. Check Incident Status
   • Incident may already be resolved
   • Verify incident still exists in PagerDuty

Performance and Timing Issues

Sync Delays

Symptoms:

• Updates take longer than expected to sync
• Several minutes delay between action and sync

Expected Behavior:

• Normal latency: 1-5 seconds
• Acceptable delays: Up to 30 seconds
• Occasional delays: Up to 1 minute during high load

Solutions:

1. Check Service Status
   • Visit PagerDuty status page
   • Visit Linear status page
   • Service issues can cause delays
2. Wait and Retry
   • Temporary delays are normal during high event volume
   • Wait 2-3 minutes before investigating
3. Verify Webhooks Active
   • Check both Linear and PagerDuty webhooks are active
   • Inactive webhooks prevent sync
4. Check for Rate Limiting
   • Very high event volume may trigger rate limits
   • Events will be queued and processed

Missing Historical Data

Symptoms:

• Old Linear issues didn't create incidents
• Past issues not synced after creating rules

Expected Behavior:

• Integration Hub only processes NEW events after webhooks are created
• Historical issues are NOT retroactively processed
• Only issues created/updated after webhook creation trigger rules

Solutions:

• For Future Issues: Webhooks and rules will work correctly for new issues
• For Existing Issues: Update the issue (change priority, add comment, etc.) to trigger webhook

Common Configuration Mistakes

Mistake 1: Monitoring Completed/Canceled Status

Problem: Rule monitors "Completed" or "Canceled" status types

Why It's Wrong: These are terminal states—issues are already resolved

Solution: Monitor active states like Triage, Unstarted, Started instead

Mistake 2: No Status Mappings

Problem: Acknowledged and Resolved status fields left empty

Why It's Wrong: Bidirectional sync won't work without status mappings

Solution: Always configure both acknowledged and resolved status mappings

Mistake 3: Too Restrictive Filters

Problem: Rule requires Urgent priority AND specific project AND specific labels

Why It's Wrong: Issues rarely match all criteria (AND logic)

Solution: Start with just priority and status filters, add more filters only if needed

Mistake 4: Overlapping Rules

Problem: Multiple rules with similar criteria creating duplicate incidents

Why It's Wrong: Same issue matches multiple rules

Solution: Make rules mutually exclusive using projects or labels

Mistake 5: No Webhook for Team

Problem: Created rule but forgot to create webhook for the team

Why It's Wrong: Rules can't work without webhooks to receive events

Solution: Always create webhook BEFORE creating rules for that team

Getting Help

Before Contacting Support

Gather this information to help resolve issues faster:

1. Connection Status
   • Screenshot of Connections tab showing status of both connections
2. Webhook Configuration
   • Which Linear team the webhook is for
   • Webhook status (Active/Inactive)
3. Rule Configuration
   • Screenshot of rule settings
   • Priority, status, project, and label filters
   • Selected PagerDuty service
   • Status mappings
4. Linear Issue Details
   • Linear issue URL
   • Issue priority, status, project, labels
   • When issue was created/updated
5. PagerDuty Incident Details (if created)
   • Incident number
   • Service name
   • When incident was created
6. Expected vs Actual Behavior
   • What you expected to happen
   • What actually happened
   • When the issue started occurring

Support Resources

• PagerDuty Support - General PagerDuty help
• PagerDuty Developer Docs - API and integration documentation
• Linear Documentation - Linear product help
• Best Practices - Configuration guidance

Diagnostic Checklist

Use this checklist to systematically diagnose issues:

Next Steps

If you've resolved your issue:

• Review Best Practices →
• Learn More About Integration Features →

If you're still experiencing issues:

• Contact PagerDuty Support with the diagnostic information above
• Check PagerDuty Status for service incidents
• Check Linear Status for service incidents