Remote Debugger - Help | Developer Portal for YouTrack and Hub

Prerequisites

Before debugging any YouTrack scripts in your IDE, you need to prepare the environment.

On the YouTrack side, check the following:

The Remote Script Debugger feature is enabled in YouTrack. This feature is group-specific, which means that only members of specific groups can use it. By default, this flag is enabled for the All Users group.

For details on how to manage optional features in YouTrack, see Optional Features.
You have sufficient permission to debug scripts.

To debug a workflow, you need to have the Update Project permission in at least one project where the target workflow is attached.
If your YouTrack Server Installation is working behind a reverse proxy, the reverse proxy is configured according to the documentation. For more details, see Reverse Proxy Configuration.

On the IDE side, check the following:

Your IDE is one of the JetBrains IDEs based on the IntelliJ Platform. This includes AppCode, CLion, DataGrip, GoLand, IntelliJ IDEA, PhpStorm, PyCharm, Rider, RubyMine, and WebStorm.
If you're using IntelliJ IDEA, the Ultimate edition is required.
If you're using PyCharm, the Professional edition is required.
The version of your IDE is 2021.1 or later.
Your IDE has JavaScript enabled.
Your IDE has the JavaScript Debugger plugin installed.
YouTrack Integration Plugin is installed, up to date, and connected to YouTrack. The minimum required version of the plugin is 2021.4.1.

For details on how to install the YouTrack Integration Plugin and connect it to YouTrack, see YouTrack Integration Plugin.

Set up the Remote Debugger

When you've prepared your IDE and the YouTrack Integration Plugin, you need to set up the debug configuration to start debugging scripts.

To add a debug configuration:

In your IDE, open the Edit Run/Debug Configurations dialog.
Click the Add New Configuration button to start creating a new debug configuration.
From the list of debug templates, select YouTrack Debug.
- The edit form for a new debug configuration for YouTrack opens.
In the edit form, set the name for the debug configuration and the root folder where the IDE will download the scripts from YouTrack.
Click OK.
- The debug configuration for YouTrack scripts is created.

Load Scripts from YouTrack

To start working with a particular script, you need to load all available scripts from YouTrack to your IDE.

To load workflow scripts from YouTrack:

Start a debugger session using the configuration you've created. Select the YouTrack debug configuration in the run/debug configurations list, and press Debug.
Wait until the debug window opens and the scripts appear in the project tree.
- A debugger session starts.
- The workflow scripts from YouTrack get loaded to your IDE. Local copies of these scripts are created in your project in the IDE.
- The workflow scripts that are available for debugging appear in the tree in the debug window.
- In the Event Log, you can see the list of scripts that were recently loaded.

Debugger Sessions

When a debugger session starts, the IDE starts to listen to events on the YouTrack side and react to the changes relevant to a particular script. You can interfere with the script execution using breakpoints, step through the script, evaluate expressions and do anything the IDE debug tools allow.

For more information on debugging in IntelliJ IDEA, see Debug Code.

Session Limitations

To ensure that debugger sessions interfere with the normal YouTrack functioning as little as possible, YouTrack limits the sessions as follows:

YouTrack allows only one active debugger session per user.
If a debugger session shows no activity for 5 minutes, it's interrupted. When a session is interrupted or stopped manually, all breakpoints become inactive and will be removed at the start of the next session.
Breakpoints stop script execution for no longer than 4 minutes. After this timeout, script execution resumes automatically.

Debug Scripts

When you've loaded scripts from YouTrack, you can start debugging them as you normally would debug any other script.

At the moment, you can only debug workflow scripts. Debugging import scripts will be supported later.

Debug Workflow Scripts

The Remote Debugger lets you debug all types of workflow rules written in JavaScript: on-change, on-schedule, state-machine, action, and custom rules. Workflows created in the Workflow Constructor are not available for debugging.

To use the debugger with a workflow rule, start a debugger session, add breakpoints, and emulate the situation in YouTrack when the workflow triggers. For example, if you're debugging an on-change rule, make the change that triggers this rule.

Start a debugger session for a workflow rule

When a breakpoint is hit, you can examine the state and behavior of the script. YouTrack remains fully functional at this time.

If you decide to modify the script after a debugger session, make changes on the YouTrack side. To continue debugging the modified script, start a new debugger session. YouTrack will load the updates at the start of the new session.

Troubleshooting

Here you can find information on the common problems with the Remote Debugger and how to solve them.

Cause	Solution
Errors when starting a debugger session. The scripts are not loaded to the debug window.	First, check the following: The Remote Script Debugger feature is enabled in YouTrack. The connection to the YouTrack Integration Plugin is successful. If the above steps don't help resolve this problem, clean the project and recreate the debug configuration as follows: Stop the debugger session. Delete the debug configuration. Remove the folder with the scripts from your project. Invalidate the caches and restart the IDE. Create a new debug configuration following the instructions above and try loading scripts again. If you continue facing issues with the debugger, collect the logs and ask for help from the YouTrack support team. Open Help > Diagnostic Tools > Debug Log Settings, add the category `com.github.jk1.ytplugin` there, and click `OK`. Restart the debugger session and reproduce the error, then collect the logs of your IDE and submit a ticket to YouTrack support. Attach the full YouTrack logs to the ticket.
Breakpoints don't have checkmarks.	Check whether the scripts are loaded in the debug window. If they do not appear in the debug window, resolve this problem first. If a breakpoint doesn't have a checkmark, it means that it's not active and it will not stop the script execution.

Cause

Solution

Errors when starting a debugger session.

The scripts are not loaded to the debug window.

First, check the following:

The Remote Script Debugger feature is enabled in YouTrack.
The connection to the YouTrack Integration Plugin is successful.

If the above steps don't help resolve this problem, clean the project and recreate the debug configuration as follows:

Stop the debugger session.
Delete the debug configuration.
Remove the folder with the scripts from your project.
Invalidate the caches and restart the IDE.
Create a new debug configuration following the instructions above and try loading scripts again.

If you continue facing issues with the debugger, collect the logs and ask for help from the YouTrack support team.

Open Help > Diagnostic Tools > Debug Log Settings, add the category com.github.jk1.ytplugin there, and click OK.

Restart the debugger session and reproduce the error, then collect the logs of your IDE and submit a ticket to YouTrack support. Attach the full YouTrack logs to the ticket.

Breakpoints don't have checkmarks.

Check whether the scripts are loaded in the debug window. If they do not appear in the debug window, resolve this problem first.

If a breakpoint doesn't have a checkmark, it means that it's not active and it will not stop the script execution.