Troubleshoot Behaviours

Behaviours are built on the UI Modifications API provided by Atlassian. Described below are some of the common errors that can occur as a result of using that API for the Behaviours feature.

If your Jira instance is using IP allow lists, you need to expand them to include the Atlassian Forge IP address range and all AWS IP ranges for your region. For more details, refer to Atlassian's IP addresses and domains for Atlassian cloud products and AWS IP Ranges.

ADF tool

If you are setting a field value which is in the Atlassian Doc Format, you can use the ADF builder tool provided by Atlassian and refer to their documentation for more details.

Uninstall Behaviours app known issue

We’re aware of an issue where, after you uninstall ScriptRunner for Jira Cloud and navigate to the Behaviours app, an incorrect screen is displayed. You should instead be prompted to install the ScriptRunner for Jira Cloud app. We are currently working on improving this experience.

Behaviours installation issues

IP allow lists

If you experience any issues whilst installing the Behaviours App, please check if your Jira instance uses IP allow lists. Before installing the ScriptRunner Behaviours app, you must include IP address ranges for outbound connections for Forge apps. The current IPs can be found in Atlassian’s documentation. Whilst IP whitelisting is not required for 2LO apps such as ScriptRunner Behaviours, adding the outbound connection IPs to the allowlist is required due to ongoing Atlassian bugs, ACCESS-1442 and FRGE-634.

If the issue persists, or you do not have IP allow lists, please contact the Adaptavist Support team.

Reinstall with multiple instances

This known issue applies to both the Forge and Connect platforms. Say you have multiple Jira Cloud sites set under the same organisation (e.g. production and sandbox sites) and decide to uninstall and reinstall the app on just one of them. This can render the app unusable on all sites, as reinstalling the app on one site triggers permissions on the other site to be revoked.

This issue is outside of Adaptavist's control, and for more details, you can refer to Atlassian's bug ticket. Additionally, ensure that Atlassian's new user management experience is enabled.

Example steps

Install the Forge app on site A.
Install the Forge app on site B.
Uninstall the Forge app from site A.

Expected results

The Forge app on site B continues working with the same permissions.

Actual results

The Forge app on site B has its permissions revoked.

Workaround

Re-install the app on site A or
Uninstall the app, and install it again on site B.

Data transfer

After copying production data to a sandbox environment, attempts to install the Behaviours app can result in an error message informing you that the installation has been unsuccessful. This issue occurs specifically when using the Add to sandbox option to install an app currently on the production site. This installation failure may be related to migration activities on the production site.

This issue is outside of Adaptavist's control, and for more details, you can refer to Atlassian's bug ticket.

Example steps

Copy production data to the sandbox.
Use the Add to sandbox option to install the app currently on the production site in a sandbox.

Expected results

The Behaviours app is installed.

Actual results

The Behaviours app fails to install, and the following error message is displayed:

Workaround

Go to Apps → Explore more apps.
Locate the Behaviours app via Search for apps.
Select the Resources section from the app Overview.
Copy the link address from the Get the descriptor file.
Go to Manage Apps.
Choose Settings → Enable private listings and Enable development mode. See Enable development mode in your site for more details.
Refresh the page, click on Upload app and insert the copied link into the app descriptor URL bar.
Click Upload.
(Optional) Disable development mode.

If the installation continues to fail, please contact the Atlassian support team for further assistance. Or, if the issue persists and none of the options above applies to your issue, please contact the Adaptavist Support team.

Behaviour script not running

Scripting language

Ensure you are using Javascript or Typescript within your script, not Groovy. Refer to Scripting in ScriptRunner for Jira Cloud for more details on our scripts.

If your behaviour script does not trigger as expected, we recommend checking the following: Is the space a Jira Service Management space? If so, JSM is currently not supported in Behaviours.

We also recommend adding logging to the first line of your script if you are using a supported product and space type. For example


logger.info(“Debugging : Script for behaviour XXX is running”)

You should verify the following:

Check the behaviour logs for the logging line once you have tried to initiate your behaviour. If the logging line is output, the script is initiating, so it's most likely the case that you have an issue with the contents of your script.
Ensure the field types you’re using in your script are currently supported in our Behaviours Supported Fields and Products.
Ensure the view you're testing the behaviour on is currently supported in our Behaviours Supported Fields and Products..
Check that you're using the correct behaviour API methods and syntax for Cloud. If you are migrating from Server/DC, the methods are different.

If you have checked the above and believe your script is correct, please contact the Adaptavist Support team, providing a copy of the script for further assistance.

Please note that our Support SLA does not cover custom scripting, including converting Server/DC scripts to the Cloud. Should you require assistance with this, please contact our Development Services team.

Field data not changing on change of work type or space

If you set a default Description or default field values based on the work type, you may find that these values remain when changing from the applicable work type to a different work type. The same is true when changing to a different space. This is a native Jira feature to prevent accidental data loss and is not enforced by ScriptRunner.

As REST APIs v3 uses the Atlassian Document Format (ADF) for fields like Comments, Description, Environment and Text Field (multi-line), you cannot clear the Description field using plain text methods like getFieldById("description").setValue("") or getFieldById("description").setValue(null).

Instead, you’ll need to set or clear the field using the ADF builder and generate the required ADF format. For example, if you enter and then remove the content in the builder, it will show you the ADF structure for an empty field.

Here’s an example of how to clear the Description field using an ADF body, which you may find helpful as a reference:

js
// Clear the Description field
getFieldById("description").setValue({
    "version": 1,
    "type": "doc",
    "content": []
})

You may also find mapping your Behaviours to all spaces or all work types helpful. Additionally, you may need to add a condition to check the space key or work type and then update or clear the Description field.

Atlassian's new transition experience in Jira is being permanently rolled out in April 2025. As a consequence, how your Jira expressions (conditions and validators) work will change. Check out our Breaking Changes section for more information.

Incorrect value type error

A common error that can occur within the ScriptRunner for Jira Cloud Behaviours feature happens when you set the wrong value type. The result of this type of error means that all changes made in the UI do not take effect, and in turn, any behaviours that have been configured on other fields also do not run.

If you have a script that uses the setValue() method and the field's value is set using the wrong data type, then you will see an error message displayed.

In this instance, you will see the error message appear on the Create Issue screen when a behaviours script fails to run, as shown below:

Resolution:

To resolve this error, ensure that you set the correct value type for the affected field. Review the Behaviours Scripts mapped to the affected work type by navigating to Behaviours > Behaviours Scripts > Affected field and then select Edit from the Actions ellipsis.

Check to ensure that the correct value for the field is set. The value types associated with each field are described on the Behaviours API page.

If you have set the wrong value type you will see a code linting error in your script. This highlights that the value being set is incorrect when writing your code, as shown below.

It's important to note that if you are setting the Description field, you will not see a warning if you set a string value and the Description field is using a Wiki Text Renderer (you can also set this field to use a Plain Text Renderer in the field configuration). In this case, we advise you to check the type configured for the Description field and set the value to Atlassian Document Format for a Wiki Text Renderer or a string for a Plain Text Renderer.

Dynamic usage of affected field

A common error that can occur when using ScriptRunner for Jira Cloud Behaviours is when users try to create dynamic scripts like the example below, and this causes the Behaviours script to fail:


let variable = "banana";
let fieldId = null;
if (variable == "banana") {
 fieldId = "customfield_10185"; //Number select list
}
 else if (variable == "apple") {
 fieldId = "customfield_10038"; //select list field
}
console.log("variable"+variable)
console.log("fieldId"+fieldId)

const field = getFieldById(fieldId);
field.setRequired(true);

The Behaviours feature does not support dynamically selecting the Affected Field within the script. The issue in the example script above is the dynamic usage of the getFieldById method. Due to Atlassian's constraints, we must automatically calculate and pass the affected fields based on the script. However, as the script is dynamic, our parser cannot identify which fields are affected.

The script needs to use the field name explicitly:


getFieldById("customfield_10185").setRequired(true);

Instead of:


const field = getFieldById(fieldId);
field.setRequired(true);