Troubleshooting & FAQ

Something looks wrong? This page collects the questions we hear most, with the usual cause and the fix for each. Start here before opening a support request; most cases are one of the situations below.

The field does not appear on the work item

• Company-managed space: does the space's field scheme make the field available, is it on the space's screens, and does a configured context cover the space?
• Team-managed space: the field must be added to the work-type layout; see Team-managed spaces.

The search suggests work items it shouldn't (or too few)

Check which context applies to the space: a space-specific context wins over the global one and has its own JQL filter (the rule, written in Jira's search language, that decides which work items the search offers). A freshly created context starts with no restriction at all.

My search text produced no results, or a Jira error

The picker no longer passes what you type into JQL as it stands. Characters JQL treats as operators, + - & | ! ( ) { } [ ] ^ ~ * ? : \ /, are replaced by spaces, and the words that remain are searched as the start of a summary. So typing Migration (Phase 2 searches for Migration Phase 2 and finds the work item, where it used to return a Jira parse error. If you type only such characters, there is no text left to search on, and the picker falls back to what the context's JQL filter alone allows.

Text shaped like a key, for example ABC-12, is looked up as a key. If no space on the site uses that prefix, the picker searches for it as text instead, so a summary containing ABC 12 can still come back.

The picker says the field is not set up for this space

The work item lives in a space that no configured context covers, or the space's field scheme does not make the field available for this work type. Jira gives every custom field a global context that cannot be deleted, and if that one has never been configured, Linker deliberately does nothing there: no suggestions, no links, no panel. Either add the space to a context you have configured, or configure the global context under Custom fields → Linker → Contexts and configuration. The Fields page shows how many contexts of a field are not set up.

The picker suddenly shows no suggestions at all

If the JQL filter uses currentIssue(), this is usually deliberate: the field it references is empty on this work item, or the work item does not exist yet, as on the create screen. A dynamic filter that cannot resolve matches nothing rather than suggesting wrong work items. Fill the referenced field first (or save the new work item), and the suggestions appear. See Dynamic JQL in the Configuration reference.

I pasted several work item keys, but some were skipped

Pasting two or more keys into the picker's search box offers to add them all at once. The offer appears only on a field that holds several work items; in a single-selection context there is nothing to add them to. A key is skipped when the work item doesn't exist, when you are not allowed to see it, or when it doesn't match the context's JQL filter, and the picker lists the skipped keys by name so you can see exactly which ones didn't make it.

Keys past the hundredth are now listed there too, instead of disappearing quietly: a Linker field holds at most 100 work items, and a longer paste is cut at that line. They appear in the same list as the genuinely missing ones, so if you pasted more than 100 keys, read the tail of that list as "over the limit" rather than "not found".

The create option doesn't appear in the picker

The Create “…” entry only shows when all of these are true: the context has Allow creating new work items from the picker switched on, a target space and work type are chosen in the Picker section of the field configuration, the app's licence is active, and you have typed something. It is also deliberately absent while the suggestions are still loading, while the picker recognises a pasted list of keys, and always in the customer portal. Remember that the new work item is created in your name: you need permission to create work items in the target space, which the permission scheme still calls Create Issues. See Create and link.

Creating from the picker fails with a message about missing fields

Linker sends only the space, the work type and the summary you typed. When the target work type requires another field that has no default value, Jira refuses, and the picker shows you Jira's own message naming those fields. Nothing was created. Give the field a default value, make it optional on that work type, or point the setting at a work type that asks for less; the Check your setup card in the field configuration names the offending fields before your users run into them. See Create and link.

A field I can't see got filled (and shows in a panel)

Screens, field schemes and contexts are three different things. A screen only controls what is visible on the work item view. The space's field scheme controls whether the field is available there at all. The field's context controls how the field behaves, and only a context with a saved configuration counts. A Linker field applies to a work item when the field scheme makes it available and a configured context covers it; then sync fills it and a panel for the field lists it, even where no screen shows it. If a field should not collect links in a space, take it out of that space's field scheme, or leave the context that covers the space unconfigured. Removing it from a screen only hides it.

The Linker panel is empty or missing

Panel visibility is controlled on the Global panels page (Jira Settings (gear) → Apps → Linker → Global panels), or, for a panel a space built for itself, on that space's Linker Panels page. It is not controlled in the field configuration. Work through these cases:

• The panel is not on the work item at all: add it via the Apps button (hexagon) in the toolbar, and choose Show for all work items in its ⋯ menu so it stays everywhere. See Work item panels.
• “No Linker panels are configured yet…”: no panel has been defined. Create one on the Global panels page, or with Create a panel for this field in a field's ⋯ menu on the Fields page.
• “No Linker panel applies to this work item.”: panels exist, but none covers this space and work type. Check the panel's scope on the Global panels page; an empty spaces or work-types list means all. A panel somebody built in another space never applies here, by design: see Space panels.
• “No linked work items.”: the panel applies, but its field or link types have no entries on this work item, or the panel's optional JQL filter hides them all.

The + in the panel gives a permission error

Which permission you need depends on the kind of panel, and the two are genuinely different. A field panel writes to the Linker field, so you need permission to edit the work item, Jira's Edit Issues permission; the panel checks that with Jira before it does anything and refuses with its own message. A link-type panel creates or deletes the native link in your own name, so Jira's Link Issues permission in that space applies and the message you see is Jira's. Ask your space admin for whichever one is missing. Note that Link Issues is not what governs a Linker field: see Who may link what.

The status button in the panel offers nothing

The menu shows exactly the transitions you may run on that work item, asked from Jira the moment you open it. An empty menu (“No transitions available for you here.”) therefore means Jira offers you none: a workflow condition blocks them, or you lack the permission in that space. This happens more often than you would expect on panels whose rows are read with the app's permission, because you can see rows there that you may not touch. See Status changes in the panel.

A status change opened a new browser tab

That transition needs a form, for example a resolution or a comment, so it cannot run silently in the panel. Linker opens Jira's own transition screen for it, already on the right transition; fill it in there and confirm. The panel shows the new status on its next refresh, when you come back to the tab or shortly after.

Work type or priority shows a name instead of an icon

Jira serves icons a site uploaded itself only to a logged-in Jira session, and an app screen is not one. Rather than showing a broken image, Linker falls back to the name, which is what the icon stood for. In the panel it first tries to fetch the icon through Jira's API, so uploaded icons usually do appear there. Nothing is wrong with your configuration. See Icons and avatars.

Everything says “App license is inactive.”

The app's Marketplace licence is not active for this site. While that is the case, the writing paths stop: the picker search, creating from the picker, adding and removing links in a panel, changing a status there, and starting a resync. Reading keeps working, the admin pages stay open, and the background sync keeps running, so nothing drifts apart in the meantime. Renew or reactivate the subscription in Settings → Apps → Manage apps; the app works again immediately afterwards, no reinstall needed.

Jira says it is too busy, or an action fails on the first try

Jira limits how many requests an app may send. Linker waits and repeats a throttled call up to three times on its own, so you rarely see this. When Jira asks for a pause longer than five seconds, the call fails right away instead of freezing the screen; try again in a moment. A resync is unaffected, it runs in the background and picks its work up again by itself.

A value sits in the field but there is no link

This can happen for a moment after a create screen, a CSV import, a bulk edit or an Automation rule, because the value arrives before the link does. Open the work item: the field repairs missing links the moment it is displayed. If the link is still missing afterwards, work through these: the context's Create native Jira links switch is off, the licence is inactive, Jira refused the link (a self-link, for example), or you deleted that link by hand. The last one is deliberate: once this field has made a link on a work item, the repair keeps its hands off, so a link you removed in Jira's own Linked work items section stays removed. The field value then follows through reverse sync and the configured delete behavior instead. See How linking works.

A link or field change hasn't shown up

Automatic updates can take a few minutes, and an already-open work item needs a page reload; see Limitations & timing.

“Who deleted my link?” / “Why did my link survive?”

That's the delete behavior setting. Default: only links Linker created are removed when someone takes a work item out of the field; hand-made links survive. Mirror mode removes any link of the configured type. And in the Never delete links mode, Linker removes no links at all; deselecting only clears the field value. See the diagram in the Configuration reference.

The last linked work item will not go away

Check whether the Linker field is marked required in that space's field configuration. Jira refuses any write that leaves a required field empty, so the moment the last entry should leave, sync cannot write the change. This used to look as though deleting a link undid itself: the value stayed behind and the link came back on the next page load. Linker now recognises the refusal and reports it with Jira's own sentence instead of quietly retrying, so it shows up in the app's logs. The fix is to make the field optional; see the note under Delete behavior.

A removed work item reappears in the field

This happens with reverse sync on whenever the delete behavior leaves the native link in place: in the default mode a hand-made link survives, and in the Never delete links mode every link does. The sync then faithfully brings the work item back. Either delete the native link itself too, or switch that context to mirror mode.

On a cloned work item this catches people out. If Jira's clone copied the links along with the field value, the app found everything already in place, created nothing, and therefore owns none of those links. In the default delete mode it will not remove them, so deselecting on the clone looks as if it did nothing. The full list of links the app will not delete is under Which links the app will delete.

A resync removed values from my field

That is the default behavior: a resync makes each field an exact mirror of the links that really exist, so an entry without a matching link is taken out. To prevent it, tick Keep existing field values (links only add) in the resync confirmation: in that mode nothing is removed, links only add missing entries. A Preview only (dry run) also shows how many work items would change before anything is written. See Resync & migration.

My field in single selection mode shows a different work item than I picked

The work item has several native links of the configured type, made by hand or through the API, and in the single selection mode the field can only mirror one of them: the newest link wins. Remove the extra links from the work item, or switch the context's Selection setting to Multiple work items (list) where several linked work items are wanted.

Users get e-mails like “Linker made an update”

Turn this on or off via Sync notifications in the Linking section; it is off by default.

A work item cannot be linked to itself

Correct: Linker blocks self-links everywhere: in the search, through the API and during sync.

Work item moved to another space

When a work item gets a new key because it moved to another space, Linker rewrites the old key in all Linker fields automatically: silently, within minutes.

Still stuck?

Open a support request; we usually answer within one business day.