- Installation & Setup
- Panels Not Showing
- Template Issues
- JQL Issues
- Custom Field Issues
- Performance
- Related Documentation
Installation & Setup
The app is installed but I don’t see any panels
- Go to Apps → Display Linked Issues settings
- Check the Module Settings tab - ensure the desired modules are enabled
- Create at least one panel configuration with Configuration Basics
- Verify the configuration is Enabled (toggle is on)
- 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
- Verify modules are enabled in Module Settings
- After enabling a module, refresh the issue page
- 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
- Is the module enabled?
- Go to Module Settings and verify the target module is toggled on
- Is the configuration enabled?
- Open the configuration and check the Enabled toggle
- Do context filters match?
- Check Project filter - does the issue’s project match?
- Check Issue Type filter - does the issue type match?
- 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
- 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
- Typo in variable name (
- Use Preview Panel to test incrementally - start with a simple template and add complexity
How do I debug template variables?
- Open the Show issue JSON tab of the configuration editor and click Download Issue Data to see all available fields and their values
- Start with
{{ issue | dump }}to see the full issue object (for debugging only) - Test individual variables:
{{ issue.fields.status.name }} - Use the
defaultfilter 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-incurrentUser()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
- Verify the Custom Field module is enabled in Module Settings
- Ensure the custom field is added to the issue layout of the issue type - the field is shown on the issue view only
- Check that a field context covers the current project and issue type
- 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
Related Documentation
- Testing Panels - Preview and debug tools
- Configuration Basics - Panel setup
- Limits - System limits and performance
- Permissions Reference - Access control details

