FAQ & Troubleshooting

Installation & Setup

The app is installed but I don’t see any panels

  1. Go to Apps → Display Linked Issues settings
  2. Check the Module Settings tab - ensure the desired modules are enabled
  3. Create at least one panel configuration with Configuration Basics
  4. Verify the configuration is Enabled (toggle is on)
  5. Check that the configuration targets the correct project and issue type

What permissions are needed to install the app?

Only Jira site administrators can install apps from the Atlassian Marketplace. After installation, configurations are managed by Jira administrators only - the app has no project settings page.

Modules are not appearing in the expected locations

  1. Verify modules are enabled in Module Settings
  2. After enabling a module, refresh the issue page
  3. Check that your browser is not caching old content (try hard refresh)

Panels Not Showing

If a panel isn’t appearing where you expect it, work through this checklist:

Diagnostic Checklist

  1. Is the module enabled?
    • Go to Module Settings and verify the target module is toggled on
  2. Is the configuration enabled?
    • Open the configuration and check the Enabled toggle
  3. Do context filters match?
    • Check Project filter - does the issue’s project match?
    • Check Issue Type filter - does the issue type match?
  4. Does the Display JQL match?
    • Test the Display JQL in Jira’s Issue Navigator with the specific issue
    • For parametric JQL, use Test JQL to see the resolved query
  5. Does the Display Condition match?
    • Use the Test Context feature to check all conditions at once

Tip: Use the Test Context button in the configuration editor to check all conditions for a specific issue at once.


Template Issues

My template shows raw text instead of rendered content

  • Verify template syntax: variables use {{ double braces }} and logic uses {% block tags %}
  • Check for unclosed tags: every {% if %} needs {% endif %}, every {% for %} needs {% endfor %}

Template shows an error message

  • Check the error details - they usually include the line number and description
  • Common causes:
    • Typo in variable name ({{ isue.key }} instead of {{ issue.key }})
    • Missing closing tag
    • Invalid filter name
    • Unclosed string in condition
  • Use Preview Panel to test incrementally - start with a simple template and add complexity

How do I debug template variables?

  1. Open the Show issue JSON tab of the configuration editor and click Download Issue Data to see all available fields and their values
  2. Start with {{ issue | dump }} to see the full issue object (for debugging only)
  3. Test individual variables: {{ issue.fields.status.name }}
  4. Use the default filter to handle null values: {{ issue.fields.assignee.displayName | default("Unassigned") }}

Template is slow or times out

  • The template engine has an 800ms timeout and a 10,000 iteration limit
  • Avoid heavy operations inside loops (nested loops, complex filters)
  • Use | take(N) to limit loop iterations
  • Reduce the number of linked issues with a lower Max Issues setting
  • See Limits for all template engine constraints

JQL Issues

Parametric JQL not resolving

If template variables in JQL aren’t being replaced:

  • Ensure the JQL field contains valid template syntax: {{ issue.key }}
  • Use Test JQL to see the resolved query
  • Check that the variable path exists in the issue data (Show issue JSON tab → Download Issue Data)
  • Add | default("") to prevent errors from null values

“User does not have permission” error

  • The JQL runs as the viewing user by default
  • If the user doesn’t have permission to browse certain projects, those issues won’t appear
  • Linked issues are always read as the viewing user - this edition has no actor setting

currentUser not working in JQL

  • In data-source JQL (the query that loads issues for the panel), use {{ currentUser.accountId }} - not Jira’s built-in currentUser() function.
  • currentUser() works in Display JQL (visibility condition) because that runs as native Jira JQL.
  • Full rule and side-by-side comparison: Display Conditions → currentUser() vs currentUser.accountId.

Custom Field Issues

Custom field not appearing on screens

  1. Verify the Custom Field module is enabled in Module Settings
  2. Ensure the custom field is added to the issue layout of the issue type - the field is shown on the issue view only
  3. Check that a field context covers the current project and issue type
  4. Verify a configuration exists for the specific field context

Field shows empty on certain issue types

  • Each field context needs its own configuration
  • If no configuration exists for a context, the field displays as empty
  • Open the field’s context settings and configure the table for that context

Custom field configurations disappearing

  • Display Linked Issues runs an hourly cleanup scheduler that detects deleted fields and removed contexts
  • If a custom field is deleted in Jira, its configurations are automatically disabled
  • If a field context is removed, the associated configuration is disabled
  • Disabled configurations can be found in the configuration list and re-enabled if the field/context is restored

Performance

Panels are slow to render

  • Reduce Max Issues - start with 50 and increase only if needed
  • Simplify JQL queries - avoid text ~ "keyword" on large datasets
  • Use indexed fields in JQL: project, status, assignee, priority
  • Reduce the number of table fields - each field adds to rendering time
  • Simplify template logic - avoid nested loops and complex calculations
  • See Limits for performance recommendations

Too many API calls

  • Each panel with a JQL or Linked Issues data source makes API calls to load issue data
  • Consider combining information into fewer panels rather than many small ones
  • Use Display JQL conditions to prevent unnecessary data loading when the panel wouldn’t be shown