Skip to main content

Troubleshooting Linear Integration

Common issues with the Linear integration and how to fix them.

Connection Issues​

"Failed to connect to Linear"​

Symptoms: Clicking "Connect Linear" fails or redirects back without connecting.

Common causes:

  • Pop-up blocker preventing OAuth window
  • Browser privacy settings blocking third-party cookies
  • Network connectivity issues

How to fix:

  1. Disable pop-up blockers for Distil
  2. Try in an incognito/private window
  3. Check browser settings allow cookies from linear.app
  4. Try a different browser

"No teams found"​

Symptoms: After connecting, the team dropdown is empty.

Causes:

  • Your Linear account has no team access
  • Linear API timeout
  • Permission issue

How to fix:

  1. Log in to Linear directly and verify you can see teams
  2. Ask your Linear admin to grant you team access
  3. Refresh the Distil integration settings page
  4. Disconnect and reconnect if still failing

"OAuth token expired"​

Symptoms: Integration was working, now shows "Unauthorized."

Cause: You revoked Distil's access in Linear settings.

How to fix:

  1. Go to Settings → Integrations in Distil
  2. Click "Disconnect Linear"
  3. Click "Connect Linear" again
  4. Re-authorize

Push Failures​

"Failed to push: Unauthorized"​

Symptoms: Push fails with "Unauthorized" error.

Causes:

  • Linear access was revoked
  • Your Linear account was deactivated
  • Team permissions changed

How to fix:

  1. Reconnect Linear (Settings → Integrations)
  2. Verify your Linear account is still active
  3. Ask Linear admin to check your team permissions

"Failed to push: Team not found"​

Symptoms: Push fails with "Team not found" error.

Causes:

  • Team was deleted or archived in Linear
  • Team permissions changed
  • You lost access to the team

How to fix:

  1. Go to Settings → Integrations in Distil
  2. Select a different default team
  3. Try pushing again

"Failed to push: Rate limit exceeded"​

Symptoms: Multiple pushes fail with "Rate limit" error.

Cause: Linear enforces API rate limits (though they're generous).

How to fix:

  1. Wait 5-10 minutes
  2. Use bulk push instead of individual pushes
  3. Contact Linear support if hitting limits frequently

Linear rate limits:

  • 1,000 requests per hour (typical usage)
  • 5,000 requests per hour (authenticated)

You're unlikely to hit this with normal use.

"Failed to push: Timeout"​

Symptoms: Push hangs and eventually fails.

Causes:

  • Linear API is slow or down
  • Network connectivity issues
  • Very large card description

How to fix:

  1. Wait a few minutes and try again
  2. Check Linear Status for outages
  3. Try pushing a different card to isolate the issue
  4. Shorten the card description if it's extremely long

After Pushing​

Symptoms: Clicking the Linear link from Distil shows 404 or "Issue not found."

Causes:

  • Issue was deleted in Linear
  • Issue was moved to a team you don't have access to
  • Linear workspace URL changed

How to fix:

  1. Search for the issue ID (e.g., "PROD-123") directly in Linear
  2. If deleted, the issue is gone - can't recover from Distil
  3. If moved, ask for access to the new team

Symptoms: The "View in Distil" link in Linear fails.

Causes:

  • Card was deleted in Distil
  • Distil URL changed
  • Link formatting issue

How to fix:

  1. Search for the card title in Distil
  2. If found, manually copy the correct link to Linear
  3. If not found, the card was deleted

"Duplicate issues created in Linear"​

Symptoms: Pushing the same card twice creates two Linear issues.

Cause: Network issue caused the first push to appear failed, but it actually succeeded.

How to fix:

  1. Delete or cancel the duplicate in Linear
  2. Keep the issue you want
  3. Update the Distil card with the correct Linear link if needed

Prevention: Wait for confirmation message before retrying a push.

Labels and Tags​

"Distil tags not showing as Linear labels"​

Symptoms: Pushed card has tags in Distil, but Linear issue has no labels.

Causes:

  • Label auto-creation failed
  • Linear team has strict label permissions
  • Tag names contain invalid characters

How to fix:

  1. Manually add labels to the Linear issue
  2. Check Linear team settings for label creation permissions
  3. Remove special characters from Distil tags (use alphanumeric only)

"Too many labels in Linear"​

Symptoms: Linear issue has dozens of labels from Distil tags.

Cause: You over-tagged cards in Distil.

How to fix:

  1. Review your Distil tagging strategy
  2. Use fewer, more meaningful tags
  3. Clean up unnecessary tags before pushing
  4. Manually remove excess labels in Linear

Best practice: Use 2-4 tags per card maximum.

Permission Issues​

"Permission denied creating issue"​

Symptoms: Push fails with "Permission denied" or "Forbidden."

Causes:

  • You don't have issue creation permission in the team
  • Team is archived or read-only
  • Linear workspace trial expired

How to fix:

  1. Ask your Linear admin to grant you issue creation permission
  2. Select a different team where you have permissions
  3. Verify your Linear workspace is active (not expired trial)

"Can't select certain teams"​

Symptoms: Some teams don't appear in the dropdown.

Cause: You don't have access to those teams.

How to fix:

  1. Ask your Linear admin to add you to the team
  2. Or use a team you already have access to

Performance Issues​

"Integration feels slow"​

Symptoms: Pushing takes longer than expected (>10 seconds).

Causes:

  • Network latency
  • Linear API performance
  • Large card descriptions

How to check: Linear is typically very fast (1-3 seconds per push). If consistently slow, there's a problem.

How to fix:

  1. Check Linear Status
  2. Test your internet connection
  3. Try from a different network
  4. Contact Distil support if consistently slow

Configuration Issues​

"Can't change default team"​

Symptoms: Saving team configuration fails or doesn't persist.

Causes:

  • Browser caching issue
  • Permission problem
  • Network timeout

How to fix:

  1. Hard refresh (Cmd+Shift+R or Ctrl+Shift+R)
  2. Try in incognito/private window
  3. Clear browser cache
  4. Make sure you're an admin in Distil

"Team dropdown won't load"​

Symptoms: After connecting, team dropdown shows loading spinner indefinitely.

Causes:

  • Linear API timeout
  • Network issue
  • Browser problem

How to fix:

  1. Refresh the page
  2. Disconnect and reconnect Linear
  3. Try a different browser
  4. Check browser console for errors (F12 → Console)

Bulk Push Issues​

"Bulk push partially fails"​

Symptoms: Some cards push successfully, others fail.

Cause: Expected behavior. Distil processes each card independently.

Common reasons for partial failures:

  • Some cards already pushed (skipped)
  • Some cards not accepted (skipped)
  • Some cards hit permission issues (failed)

How to fix: Review bulk push results:

  • Succeeded: Done
  • Skipped: Check why (usually already pushed or not accepted)
  • Failed: Retry individually to see specific error

"Bulk push is slow"​

Symptoms: Takes longer than expected for multiple cards.

Cause: This is normal. Each push takes 1-3 seconds.

Expected time: 10 cards = ~15-20 seconds, 50 cards = ~60-90 seconds

No action needed unless taking much longer than this.

Comparing with Jira​

If you use both integrations:

IssueLinearJira
Setup complexitySimplerMore complex
Connection issuesRareMore common
Permission problemsClear errorsAmbiguous errors
PerformanceVery fastModerate
Rate limitsHigh (unlikely to hit)Lower (easier to hit)

Linear is generally more reliable and easier to troubleshoot than Jira.

Getting More Help​

Check Linear Status​

Visit status.linear.app to see if there are known outages.

Linear Support​

For Linear-specific issues (not Distil integration):

Distil Support​

For integration issues:

  1. Note the exact error message
  2. Note when it started
  3. Screenshot if applicable
  4. Email support@distil.app

Response within 24 hours.

Preventing Issues​

Best Practices​

Test after Linear changes: If your Linear admin changes team structure or permissions, test a push to ensure integration still works.

Use bulk push: More efficient and less likely to hit rate limits than pushing one-by-one.

Keep Linear active: If your Linear trial expires, the integration stops working.

Monitor permissions: Ensure your Linear account maintains issue creation permissions.

Don't over-tag: Use 2-4 meaningful tags per card to avoid label clutter in Linear.

Common Questions​

Q: Can I push to multiple Linear teams? A: Yes. Set a default team, but override per-push via "Advanced Options."

Q: What if I switch Linear workspaces? A: You'll need to disconnect and reconnect Distil to the new workspace.

Q: Can I sync changes from Linear back to Distil? A: Not currently. Push is one-way (Distil → Linear). Updates in Linear don't sync back.

Q: What if my Linear trial expires? A: The integration stops working. Upgrade to a paid Linear plan, then reconnect in Distil.

Q: Can I push the same card to both Linear and Jira? A: No. Each card can be pushed to one integration at a time. Choose one.

Next Steps​