Two-project sync - troubleshooting

Where to look first

When a sync misbehaves, work through these in order:

  1. Sync list - the row’s colour, the Paused and Bot fallback badges, and the Pending conflicts and Failed items counts.
  2. 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.
  3. View activity (row menu) - recent runs and the pending dead-letter items, with the error category of each.
  4. 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, fail for 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.


JiBrok Studio for Jira Cloud JiBrok Studio for Jira Cloud
Release notes
Core Features
Triggers
Extensions
Data Storage
Scripting Overview
JavaScript Engine
Python Engine
Groovy Engine
Scripting API
Administration
Guides