Triage for Jira: troubleshooting
Everything here starts from something you can actually see on screen.
Before you work through any of it, open the Dashboard and look at the delivery log. It records every webhook that arrived and why it did what it did, and it answers most of these questions outright.
Nothing is arriving
Setup says "Waiting for first event" and never changes
Nothing has reached your webhook URL yet. Four things cause this, roughly in order of how often:
No alert is connected to the error monitor. Creating the integration in Sentry doesn't deliver anything by itself. Check Sentry → Monitors → your project's Error Monitor → Connected Alerts. If that list is empty, that's your answer, and step 4 of the setup guide covers it.
The alert triggers on the wrong thing. If it fires on "an issue is resolved" or "an issue escalates" but not "a new issue is created", then a brand new error won't set it off.
No new issue has actually happened. Sentry groups repeated errors into a single issue, and an error that joins an existing group isn't a new issue, so it won't trigger the alert. If you're testing, cause an error Sentry hasn't seen before: a different message and a different stack trace.
The webhook URL is wrong. Compare what's in Sentry against the Connections tab character by character. The long id on the end identifies the connection, so a URL that got truncated on the way across points nowhere.
Setup shows a red "Signature mismatch"
Deliveries are arriving and being turned away. The Client Secret stored here doesn't match the one in Sentry.
Copy it again from Sentry → Custom Integrations → your integration, and check you've taken the Client Secret rather than the Client ID. Paste it into step 3 of the Setup tab, making sure the picker is naming the right connection.
The Errors webhook checkbox is greyed out
That's expected below a Business plan, and the app doesn't need it. Sentry restricts the Errors webhook to Business and Enterprise. Events reach this app through the alert action instead, which every plan has. Tick Issues and leave Errors alone.
All the webhook checkboxes are greyed out
Set Permissions → Issue & Event to Read first. Sentry disables them until a scope grants access and doesn't explain why.
Events arrive but no work items appear
Open the delivery log. Every row carries a reason, and it'll be one of these.
"no rule matched (event came from a different Sentry connection)" means the rule belongs to a different connection. Rules aren't shared between Sentry organisations. Create a rule for this one.
"level warning is not in [error]" means the event's level isn't among the levels ticked on the rule. Either tick it, or untick all of them to match any level.
"Sentry project 4506… does not match 4501…" means the rule has a Sentry project id set and the event came from a different project. Clear that field to match every project in the organisation.
"hourly cap reached" means the rule has already created its quota for this hour. The error is still in Sentry and will create a work item next time it fires. If the volume is expected, raise or remove the cap on the rule.
"threshold not reached, 2 of 5 events received since install" means the rule waits for a minimum number of events. The work item appears once enough have arrived.
A rule marked "never runs" has another rule above it that matches everything it would, and evaluation stops at the first match. Move it above the other one, or narrow the other one. The warning tells you which rule is in the way.
"no Jira work item is linked to this Sentry issue" on an issue.created row is harmless. Sentry's issue webhooks carry no event data, so they go to the status sync path, which has nothing to act on until a work item exists. The work item comes from the alert delivery instead.
Work items appear but something's missing
Sentry Error Count and Sentry Issue are empty
Nearly always a team-managed project, which doesn't inherit global custom fields.
Go to Project settings → Fields and add both. Then Project settings → Work types, pick your work type, drag both onto the layout, and save.
The Rules tab warns about this when it can detect it. Company-managed projects aren't affected.
In the meantime, JQL on sentryIssueId and sentryEventsSinceInstall still works, because those
come from an indexed issue property rather than a custom field.
The Sentry error panel isn't on the work item
Jira doesn't render app panels automatically. Open it from the Apps button, the hexagon under the work item title next to the plus sign, and choose Sentry error.
The panel says "Not enabled for this project"
The project isn't ticked under Apps → Triage for Jira → Projects. Everything is off until you turn it on.
There are two Sentry panels on one work item
One is ours, called Sentry error. The other belongs to Sentry's own Jira integration. They're independent and don't interfere with each other.
The count in the description doesn't match the field
Both are right. The description is written once, when the work item is created, and never rewritten, which is why it says "Events since install when this was created". Rewriting it every time a duplicate arrived would burn API calls and overwrite anything you'd edited. The Sentry Error Count field and the panel carry the running total.
The count is off by one or two after a burst
The event count is a read-modify-write. When many events for the same error arrive within a second or two, two jobs can read the same value and one of the increments is lost. Seeding sixty-four events in about two seconds produced a count of sixty-three.
It needs the same unrealistic burst as the duplicate work items above, and the figure is described everywhere as the webhooks this app has received rather than an exact ledger. Normal traffic arrives far enough apart that it does not happen.
The count is lower than what Sentry shows
That's expected, and it's labelled as such everywhere it appears. This app counts the webhooks it has received since it was installed. Sentry's lifetime total for an issue isn't in the webhook payload, and fetching it would mean calling Sentry, which would cost the Runs on Atlassian badge. An error that already existed when you installed the app will always show a lower number here.
Local variables and request headers are missing from the stack trace
They're removed before anything is stored. Sentry stack frames routinely carry API keys, session cookies, authorization headers and personal data in vars, cookies, headers and extra. Frames are rebuilt from a short list of fields that are safe to keep: filename, function, line number and the source line. Query strings come off request URLs for the same reason. The privacy policy has the detail.
Duplicates
Two work items for the same Sentry error
Usually Sentry's own Jira integration. Its manual Create Jira Issue button makes a work item this app can't see, and seeing it would mean calling Sentry.
The fix is to link them. On the work item the button created, open the Sentry error panel and paste the Sentry issue URL. After that, deduplication catches every event for that issue.
Sentry's free Developer plan doesn't offer that button, so this can't happen there.
Several work items appeared for one error, all at once
Deduplication can lose a race. The webhook endpoint returns as soon as it queues an event, and the work is done afterwards by jobs that run in parallel. If many events for the same Sentry issue arrive within a second or two of each other, several of those jobs can check "does a work item exist for this issue yet?" before any of them has finished creating one, and each decides to create.
Both of the defences have the same blind spot. The link record is written at the end of the job that creates the work item, and the JQL duplicate guard searches an index that updates a moment later. Neither is visible to a sibling job a few milliseconds behind.
In practice this needs a burst. A Sentry alert on "a new issue is created" fires once per issue, so the usual path sends one delivery and the repeats arrive minutes or hours apart, which is far outside the window. It was found by a seeding script firing sixty-four events for one error back to back, which is not something Sentry does.
If it happens, delete the extras. The link points at one of them and everything afterwards deduplicates onto that one correctly.
A duplicate appeared after I deleted a work item
The app keeps a record pointing at the work item it created for each Sentry issue. Delete the work item and the next event makes a new one. That's intended: deleting the work item is how you tell it to start over.
How it works, and why
Why doesn't the app call Sentry?
Any outbound call would cost the Runs on Atlassian badge, which certifies that app data stays on Atlassian infrastructure. Staying inbound-only is what earns that badge, and it's also why the app works on Sentry's free plan and with self-hosted Sentry behind a firewall.
It costs two things, and both are stated wherever they show up. The app can't read Sentry's lifetime event count, and it can't see work items created by Sentry's own integration.
Why is there an hourly cap on each rule?
Deduplication only helps when the same error repeats. A bad deploy produces hundreds of different Sentry issues in minutes, each with its own id, each matching the same rule. Without a cap that turns into hundreds of tickets at the worst possible moment. Capped events stay in Sentry, appear in the delivery log with the reason, and create work items next time they fire.
The cap is per rule, per clock hour, and it's on by default. Set it to 0 if you genuinely want no limit.
Why does this app work when ad blockers break others?
The whole interface is served from Atlassian's own infrastructure. There's no third-party script, font, stylesheet, CDN or analytics endpoint anywhere in it, so a blocker or privacy extension has nothing to intercept. A test checks this on every build.
Does it work with self-hosted Sentry?
Yes, with nothing extra to configure. Your Sentry instance makes an outbound call to Atlassian and nothing calls in, so there's no allowlist to edit. Set your base URL on the connection so links resolve.
Can two Sentry organisations share one connection?
No. A connection attaches to the first Sentry organisation that posts to it and refuses every other one after that. That's what keeps their work items, counters and rules separate, and it can't be reassigned. Create a second connection.
What happens when I uninstall?
Everything the app stored is deleted: connections, encrypted Client Secrets, rules, links, counters and the delivery log. Work items it created stay, because they're ordinary Jira work items, and the values already written into their fields and descriptions stay with them.
If you only want to stop deliveries, remove the connection instead. To stop one rule, switch it off.
Free and Pro
The free tier covers one Sentry organisation, three rules, manual linking, the issue panel and both custom fields.
Pro adds unlimited organisations and rules, status sync from Sentry, the dashboard and delivery log, and the advanced rule filters: environments, event thresholds and title patterns.
Rules past the free allowance show as "paused, free tier". They stay visible and editable and start working again when a licence is added. Nothing is deleted.