Skip to main content

Troubleshooting Jira Integration

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

Connection Issues​

"Failed to connect to Jira"​

Symptoms: Clicking "Connect Jira" fails or times out.

Common causes:

  • Network connectivity issues
  • Atlassian services temporarily down
  • Pop-up blocker preventing OAuth window

How to fix:

  1. Check your internet connection
  2. Disable pop-up blockers for Distil
  3. Try connecting in an incognito/private window
  4. Check Atlassian Status for outages

"OAuth token expired"​

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

Cause: OAuth tokens automatically expire, but the refresh failed.

How to fix:

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

This gives you a fresh token. Your previously pushed issues remain linked.

"No projects found"​

Symptoms: After connecting, the project dropdown is empty.

Causes:

  • Your Jira account has no project access
  • Jira privacy settings preventing API access
  • Network timeout loading projects

How to fix:

  1. Log in to Jira directly and verify you can see projects
  2. Ask your Jira admin to grant you project access
  3. Try refreshing the Distil integration settings page
  4. Disconnect and reconnect if still failing

Push Failures​

"Failed to push: Unauthorized"​

Symptoms: Push button fails with "Unauthorized" error.

Causes:

  • OAuth token expired
  • Jira permissions changed
  • Account deactivated in Jira

How to fix:

  1. Reconnect Jira (Settings → Integrations)
  2. Verify your Jira account still has access
  3. Ask Jira admin to check your permissions

"Failed to push: Project not found"​

Symptoms: Push fails with "Project not found" or similar error.

Causes:

  • Project was deleted or archived in Jira
  • Project permissions changed
  • Project key changed

How to fix:

  1. Go to Settings → Integrations
  2. Reconfigure your default project (select a different one)
  3. Try pushing again

"Failed to push: Required field missing"​

Symptoms: Push fails with "Field 'X' is required" error.

Cause: Your Jira project has custom required fields that Distil doesn't populate.

Common culprits:

  • Epic Link (required in some configurations)
  • Sprint (required in some configurations)
  • Custom priority or severity fields

How to fix:

Option 1: Make the field optional in Jira:

  1. Go to Jira Project Settings → Issue Types
  2. Find the field and click "Optional" instead of "Required"

Option 2: Use a different project:

  1. Create a new "Product Backlog" project in Jira without custom required fields
  2. Configure Distil to use that project

Option 3: Contact support if you can't change Jira settings

"Failed to push: Rate limit exceeded"​

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

Cause: Atlassian enforces API rate limits. You've made too many requests in a short time.

How to fix:

  1. Wait 5-10 minutes before trying again
  2. Use bulk push instead of pushing cards individually
  3. Avoid pushing more than 50 cards in a 5-minute window

"Failed to push: Timeout"​

Symptoms: Push hangs and eventually fails with timeout error.

Causes:

  • Jira API is slow or overloaded
  • Network connectivity issues
  • Large card description causing slow processing

How to fix:

  1. Wait a few minutes and try again
  2. Check Atlassian Status for performance issues
  3. Try pushing a different (smaller) card to isolate the issue

After Pushing​

Symptoms: Clicking the Jira link from Distil shows 404 or access denied.

Causes:

  • Issue was deleted in Jira
  • Issue was moved to a project you don't have access to
  • Jira site URL changed

How to fix:

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

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

Causes:

  • Card was deleted in Distil
  • Distil URL changed
  • Card ID changed (unlikely but possible after data migration)

How to fix:

  1. Search for the card title in Distil
  2. If found, manually update the Jira issue description with the correct link
  3. If not found, the card was likely deleted

"Duplicate issues created in Jira"​

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

Cause: Network issue caused the first push to not register properly, but it actually succeeded.

How to fix:

  1. Delete or close the duplicate issue in Jira
  2. Keep the one you want
  3. Manually update the Distil card with the correct Jira link if needed

Prevention: Wait for push to complete (see success message) before trying again.

Configuration Issues​

"Can't change default project"​

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

Causes:

  • Browser caching issue
  • Permission problem
  • Network timeout

How to fix:

  1. Hard refresh the page (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows)
  2. Try in an incognito/private window
  3. Clear browser cache and try again
  4. Make sure you're an admin in the Distil workspace

"Issue type dropdown is empty"​

Symptoms: After selecting a project, no issue types appear.

Causes:

  • Project has no issue types configured (rare)
  • API timeout loading issue types
  • Permissions issue

How to fix:

  1. Refresh the page and try again
  2. Select a different project (one you're sure has Task or Story types)
  3. Verify in Jira that the project has issue types configured

Bulk Push Issues​

"Bulk push partially fails"​

Symptoms: Some cards push successfully, others fail.

Cause: This is expected behavior. Distil processes each card independently.

Common reasons for partial failures:

  • Some cards already pushed (skipped)
  • Some cards not accepted yet (skipped)
  • Some cards hit rate limits (failed)

How to fix: Review the bulk push results:

  • Succeeded: These are done
  • Skipped: Check why (usually already pushed or not accepted)
  • Failed: Retry these individually to see specific error messages

"Bulk push is very slow"​

Symptoms: Bulk push takes longer than expected.

Causes:

  • Jira API is slow
  • Large number of cards being pushed
  • Each card has a large description

This is normal: Bulk pushes process cards in parallel, but Jira API latency still applies. Expect ~2-3 seconds per card on average.

No action needed unless it's taking more than 5 seconds per card consistently.

Permission Issues​

"Permission denied creating issue"​

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

Causes:

  • Your Jira account doesn't have "Create Issue" permission in the target project
  • Project permissions were changed
  • Account role was downgraded

How to fix:

  1. Ask your Jira admin to grant you "Create Issue" permission
  2. Or select a different project where you have permissions
  3. Verify permissions by manually creating an issue in Jira

"Can't select certain projects"​

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

Cause: You don't have access to those projects in Jira.

How to fix:

  1. Ask your Jira admin to grant you access
  2. Or use a project you already have access to

Performance Issues​

"Integration feels slow"​

Symptoms: Listing projects, loading issue types, or pushing cards takes a long time.

Causes:

  • Jira API latency (especially for large Jira instances)
  • Network issues
  • Jira performance problems

How to check:

  1. Go to Settings → Diagnostics → Jira Integration (admins only)
  2. Look at the p95 latency metric
  3. If consistently >5000ms, there's a problem

How to fix:

  • Check Atlassian Status
  • Contact Distil support if diagnostics show consistently high latency

Getting More Help​

Check Diagnostics (Admins Only)​

Go to Settings → Diagnostics → Jira Integration to see:

  • Success rate over the past 30 days
  • Error breakdown by type
  • Recent failures with details
  • Performance metrics

This helps identify patterns (e.g., "all failures are rate limits" vs. "all failures are permission errors").

Contact Support​

If you can't resolve the issue:

  1. Note the exact error message
  2. Note when it started happening
  3. Screenshot the failure (if visible)
  4. Check diagnostics (if admin)
  5. Email support@distil.app with this info

We'll investigate and respond within 24 hours.

Preventing Issues​

Best Practices​

Reconnect periodically: If you haven't pushed in 60+ days, consider reconnecting Jira proactively.

Monitor diagnostics monthly: Admins should check integration health once a month.

Use bulk push: Reduces API calls and is more efficient than pushing cards one by one.

Keep Jira permissions stable: Avoid frequently changing project permissions or moving projects.

Test after Jira changes: If your Jira admin makes changes to projects or permissions, test a push to ensure Distil still works.

Next Steps​