- Where to look first
- Error categories
- View activity
- Failed items (dead-letter) and retry
- Automatic pause and Resume sync
- Bot fallback
- Common runtime issues
- Data hygiene
- Related
Where to look first
When a sync misbehaves, work through these in order:
- Sync list - the row’s colour, the Paused and Bot fallback badges, and the Pending conflicts and Failed items counts.
- Notifications (the bell in the Admin Panel header) - Paused, Recent run failed, Recent run partial, Items pending retry, Items stuck >30 days, Conflicts pending, each with Go to config.
- View activity (row menu) - recent runs and the pending dead-letter items, with the error category of each.
- Run pre-flight check in the editor - re-checks fields, statuses and accounts against the live site.
Error categories
Every failed issue is tagged with one category. You see it in View activity and in the Sync error dialog.
| Category | Typical cause | What to do |
|---|---|---|
| Authentication | Jira rejected the app’s or the bot’s credentials | Check that the app is installed and its permissions are approved; check the bot account is active |
| Permission | The identity used (app, bot or original author) may not perform the action in the target project | Grant the missing permission - see Permissions setup |
| Not found | The counterpart, field, status or project no longer exists, or is not visible | Re-run the pre-flight check; fix the mapping |
| Validation | Jira rejected a write: required field missing, field not on the screen, incompatible value | Add the field to the rules, use When target field is missing = default-value, or turn on type coercion where safe |
| Workflow transition | The status could not be reached: no direct transition, or the transition needs a field the sync does not write | Fix the status mapping in the Workflow diff panel, or adjust the target workflow |
| JSM request type | No request type could be resolved for the issue type | Add the row to Issue type to request type, or rename to match with Auto-map request type by name |
| JSM customer | The reporter or customer could not be set on the request | Check the Customer policy and the bot / customer account IDs |
| JSM scope missing | The app lacks a service desk permission | Approve the app’s pending permissions - see Permissions setup |
| Rate limit | Jira throttled the requests | Usually transient - Retry failed items later, or use a longer Schedule interval |
| Network / 5xx | Jira or the network failed | Transient - retry |
| Unknown | Anything else | Open the Sync error dialog and follow its Suggested action; quote the correlation ID when contacting support |
Error texts are stored with emails and account IDs redacted.
View activity
View activity (row menu) opens the history of the sync.
Recent runs lists each run with its trigger and N ok / N failed / N skipped of N counts. Filter by status and trigger; View sample shows the recorded errors.
Clicking an error opens Sync error with:
| Field | Meaning |
|---|---|
| Category | One of the error categories |
| HTTP status, endpoint | The Jira response that failed |
| Actor | The identity the call was made as |
| Correlation ID | Quote it when reporting issues |
| Response body preview | The start of Jira’s answer, redacted |
| Suggested action | What to fix first |
Failed items (dead-letter) and retry
Failed items are issues that failed and wait for retry. An issue lands here when, for example:
- Jira rejected a write the app could not recover from.
- A policy is set to fail: Fail and route to dead-letter for issue types,
failfor statuses or fields. - When the linked issue is not synced is Report it in the run and the other end is not synced yet.
- Jira did not return a full list the sync needs - see “Jira did not return the full list”.
Looking at failed items
In View activity, Pending dead-letter items shows Source issue, Category, Error and Failed at for each item. The Failed items column of the sync list shows the count.
Retrying after a fix
When you have fixed the underlying issue (added a field rule, mapped a status, granted a permission):
- Retry this item - retries one issue.
- Retry failed items (row menu, only when there are failed items and the sync is not paused) - starts a job that retries all of them.
- Scheduled runs also retry failed items first, up to 50 per run.
Mark ignored (per item) and Mark all as ignored drop items you do not want retried. Failed items that were ignored or later retried successfully are removed after 90 days; items still waiting for retry are kept, and the bell shows Items stuck >30 days for old ones.
Automatic pause and Resume sync
A sync is paused automatically:
- after 3 runs in a row in which more than half of the issues failed with the same error category, or
- when the type of one of the projects changes (for example, a software project becomes a service project).
A paused sync shows a red status, a Paused badge and Resume sync instead of Sync now. Before resuming, open the editor and click Run pre-flight check: resume is refused while the pre-flight check reports errors (Cannot resume: N pre-flight errors must be fixed first.).
After a project type change, check that the Jira Service Management section and the pair type (Jira ↔ Jira, JSM ↔ Jira, JSM ↔ JSM) match the projects now - JSM settings do nothing until the pair is reconfigured.
Bot fallback
With comment Author or attachment Upload as set to original, the app writes as the original author only when that user may add comments / attach files in the target project. Otherwise it uses the bot account, and then the app. The sync list then shows a Bot fallback badge for the sync.
To react, either grant the original authors access to the target project, or accept the fallback as intended (or set Author to bot or app to make it explicit).
Common runtime issues
“I changed a field rule but nothing happens”
Save the configuration, then click Sync now (or wait for the next scheduled run). Sync now processes issues updated since the last run, so an issue nobody touched is not picked up - run Backfill to process every issue in both projects. If the rule uses manual_review, the value may be waiting in Sync conflicts.
“Values are not copied - they show up as conflicts”
manual_review (the default strategy) also applies the first time a pair is compared. Fields whose values differ on a freshly created counterpart go to Sync conflicts. Use source_of_truth or last_write_wins for fields that should simply be copied. Closing a conflict with Apply A / Apply B records the decision in the audit log but does not itself write the value into the issue.
“Comments duplicate on every sync”
Copied comments are marked, so the app never copies them back or twice. If you still see duplicates, look for a Jira Automation rule or another integration that re-posts comments, and check View activity for failures on the comment step.
“First run is huge and slow”
Backfill goes over every issue in both projects and may run for a while. Watch its counts in View activity. Scheduled runs are capped at 50 issues per run, oldest first.
“Jira did not return the full list”
The sync reads lists from Jira to the end: organizations of the target (to find one by name), comments of an issue (up to 50 pages of 100), portals and request types. If Jira stops returning pages midway (an error or a timeout), the issue fails instead of acting on a partial list:
- Organizations - the app does not create the organization, so no duplicate appears on the target.
- Comments - the issue fails instead of syncing only part of the comments.
This is usually transient. Retry it from the failed items list (see Retrying after a fix). If it keeps failing, check the bot’s permissions on the target service desk.
“The sync paused itself”
See Automatic pause and Resume sync. Separately, a pre-flight check older than 30 days is repeated automatically - its errors show as Pre-flight errors and block Resume sync until fixed.
Data hygiene
- Error texts are stored with emails and account IDs redacted.
- Exported configurations leave out user references (bot, customer and similar account IDs); the export reports how many were removed.
- Every change to a configuration, every run start and every conflict decision is written to the settings audit log - see Audit logs.
Related
- Two-project sync reference
- Permissions setup - check the per-project matrix when you see a Permission error
- JSM specifics - request type, customer policy and sanitization
- Typical scenarios - reference configurations to compare against
