---
schema: rendered-html/v1
title: "Remote Debugger | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/remote-debugger.html
generated_at: 2026-06-11T15:08:26.890288+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- JavaScript Workflow Quick Start Guide
- Create a Workflow
- Edit a Workflow
- Workflow Rule Types
- Transactions
- Use Cases for Workflows
- Web-based Workflow Editor
- Using an External Code Editor
- Default Workflows
- Custom Workflow Repository
- JavaScript Workflow Reference
- Rule-specific Properties
- Context
- [Requirements](jetbrains__com__help__youtrack__devportal__requirements.md)
- Using the Workflow API
- Building Integrations with Slack
- Using REST API Methods in JavaScript Workflows
- Working with Dates and Times
- Working with Periods
- Localized Workflow Messages
- Troubleshooting Workflows
- [Remote Debugger](remote-debugger.html)
- YouTrack Workflow API
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. YouTrack Workflows
2. JavaScript Workflow Reference
3. [Remote Debugger](#0)

# Remote Debugger﻿

Last modified: 07 May 2026

The Remote Debugger lets you connect to YouTrack and debug workflow scripts using the standard functionality of your favorite IDE. The debugger loads scripts from YouTrack to your IDE, where you can debug them with the tools you're accustomed to.

Using the Remote Debugger requires a JetBrains IDE with the YouTrack Integration Plugin installed and set up.

> ### note
>
> Availability
>
> Currently, the Remote Debugger is available for YouTrack Server installations only. Support for YouTrack Cloud will be added later.

## 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:﻿

1. In your IDE, open the Edit Run/Debug Configurations dialog.
2. Click the Add New Configuration button to start creating a new debug configuration.

   [![Select the debug template](https://crawler.prototype.prolicht.digital/l/qbmATQ)](https://resources.jetbrains.com/help/img/youtrack/select-debug-template.png)
3. From the list of debug templates, select YouTrack Debug.

   - The edit form for a new debug configuration for YouTrack opens.
4. In the edit form, set the name for the debug configuration and the root folder where the IDE will download the scripts from YouTrack.

   [![Set up the YouTrack debug configuration](https://crawler.prototype.prolicht.digital/l/9vdqGW)](https://resources.jetbrains.com/help/img/youtrack/youtrack-debug-configuration.png)
5. Click OK.

   - The debug configuration for YouTrack scripts is created.

## Load Scripts from YouTrack﻿

> ### tip
>
> Requires permissions: Update Project

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:﻿

1. Start a debugger session using the configuration you've created. Select the YouTrack debug configuration in the run/debug configurations list, and press Debug.
2. Wait until the debug window opens and the scripts appear in the project tree.

   [![Loaded scripts](https://crawler.prototype.prolicht.digital/l/lnqraT)](https://resources.jetbrains.com/help/img/youtrack/loaded-scripts.png)
   - 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.

> ### note
>
> Changing Script Code
>
> Script code that you see in the IDE is always in read-only mode. The scripts that you see in the project tree are local copies of the remote scripts. These local copies are created in the IDE project so that you can use the IDE debug tools: set breakpoints, evaluate expressions, and so on.
>
> If you want to update a script, switch to the browser and make changes in YouTrack itself. Then, restart the debugger session so that the IDE loads your changes to the local copies of your scripts.

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

### Debug Workflow Scripts﻿

> ### tip
>
> Requires permissions: Update Project

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](https://crawler.prototype.prolicht.digital/l/w60SkF)](https://resources.jetbrains.com/help/img/youtrack/debug-workflow-start.png)

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

[![Examine the script state](https://crawler.prototype.prolicht.digital/l/uGzTOc)](https://resources.jetbrains.com/help/img/youtrack/debug-workflow-hit-breakpoint.png)

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:   1. Stop the debugger session. 2. Delete the debug configuration. 3. Remove the folder with the scripts from your project. 4. Invalidate the caches and restart the IDE. 5. Create a new debug configuration following the [instructions above](/help/youtrack/devportal/remote-debugger.html#add-debug-configuration) 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](https://youtrack-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66282) 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. |

- [Remote Debugger](/help/youtrack/devportal/remote-debugger.html)
- [Prerequisites](/help/youtrack/devportal/remote-debugger.html#prerequisites)
- [Set up the Remote Debugger](/help/youtrack/devportal/remote-debugger.html#debugger-setup)
- [Load Scripts from YouTrack](/help/youtrack/devportal/remote-debugger.html#load-scripts-from-youtrack)
- [Debugger Sessions](/help/youtrack/devportal/remote-debugger.html#debugger-sessions)
- [Debug Scripts](/help/youtrack/devportal/remote-debugger.html#debug-scripts)
- [Troubleshooting](/help/youtrack/devportal/remote-debugger.html#troubleshooting)

Troubleshooting WorkflowsYouTrack Workflow API

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.

![](https://bat.bing.com/action/0?ti=5220035&tm=gtm002&Ver=2&mid=b56c85c9-5c07-4dd3-a29f-67cfa7032b0e&bo=4&sid=452929b065a111f19a7fe7356f74a419&vid=aa3122f0648711f1a10d6d095e10fd87&vids=0&msclkid=N&pi=918639831&lg=en-US&sw=1920&sh=1080&sc=24&tl=Remote%20Debugger%20%7C%20Developer%20Portal%20for%20YouTrack%20and%20Hub%20Documentation&p=https%3A%2F%2Fwww.jetbrains.com%2Fhelp%2Fyoutrack%2Fdevportal%2Fremote-debugger.html&r=&lt=1068&pt=1781190502999,39,39,,,3,3,3,3,3,,3,35,36,43,417,417,417,1067,1068,1068&pn=0,0&evt=pageLoad&sv=2&asc=G&cdb=AQAS&rn=390097)
