Platform Debugger Architecture Redesign for Remote Development in 2026.1

Maksim Zuev

The IntelliJ Platform provides a powerful debugger framework that plugins can extend to support various programming languages and runtime environments. To enable remote development scenarios – where the IDE interface runs on your local machine while code executes on a remote server – we’ve redesigned the debugger architecture. This guide walks you through the changes and shows you how to migrate your plugin for 2026.1 and beyond.

Why split the debugger?

In the last several releases, we re‑architected the IntelliJ Platform debugger to support Remote Development mode. The major change visible to users is that the Debugger tool window and breakpoints are now rendered on the frontend, while the backend hosts the active debugger session and communicates with the target process. As a result, the debugger experience in Remote Development mode is much more responsive and stable. However, these changes have modified the debugger implementation and might affect existing plugins.

To provide the same experience in both Remote Development and Local IDE modes, we use a single implementation for both. Therefore, the changes described in this guide can affect plugins in both modes.

Important: This guide focuses primarily on plugin support in Local mode. For migration steps for Remote Development mode, see the section below.

What’s changed?

To support Remote Development mode, we split the debugger into two parts: frontend and backend. The frontend is responsible for rendering the Debugger tool window (frames, variables’ tree, inlays, etc.). The backend hosts the active debugger session started by a plugin and provides data to the frontend via RPC (Remote Procedure Call).

As a result of these changes, several debugger API contracts have changed.

1. The debugger UI is now created asynchronously, so older methods that access the debugger UI or the Debugger tab may cause race conditions.
2. The frontend implementation no longer works directly with entities provided by plugins via XDebugProcess and XSuspendContext. For example, XStackFrame, XValue, and other instances are no longer available on the frontend. Instead, we use FrontendXValue wrappers that cannot be cast to plugin‑specific XValue implementations.

Example: Suppose you have a plugin that implements a custom debugger. The plugin extends XDebugProcess as MyDebugProcess and provides custom implementations: MyStackFrame (which extends XStackFrame), MyValue (which extends XValue), and other entities. In addition to the backend implementation, the plugin provides an action that assumes the platform debugger UI operates on those entities directly (e.g. XValueNodeImpl contains MyValue).

Now that the debugger has been split, the platform debugger UI operates with FrontendXValue and other frontend wrappers instead (e.g. XValueNodeImpl now contains FrontendXValue). As a result, actions operating on the debugger UI may unexpectedly access frontend entities and fail to cast them to plugin entities (e.g. FrontendXValue is not an instance of MyValue). See the following sections for more details.

What should I do?

Test your plugin with the 2026.1 EAP. UI components and actions are the areas most likely to be affected.

Pay attention to error messages in the IDE log. Incorrect debugger API usage will be logged with the [Split debugger] message prefix and an explanation of the migration steps.

Two migration paths:

Depending on your plugin requirements, choose one of the following migration paths:

1. Local mode only – Migrate from the affected APIs below to the recommended ones. Your plugin will work in Local IDE mode, but some functionality may work incorrectly in Remote Development.
2. Local + Remote Development modes – Follow the Remote Development mode migration steps below to support both modes.

If you encounter unexpected API behavior, please report it in YouTrack.

Which APIs are affected in Local IDE mode?

The following APIs related to the debugger UI are deprecated and unsafe to use since 2026.1:

• com.intellij.xdebugger.XDebugSession#getRunContentDescriptor – deprecated and must not be used, as the frontend UI should not be accessed from the backend. See the Javadoc for more details.

• com.intellij.xdebugger.XDebugSession#getUI – deprecated and must not be used. Can lead to race conditions due to asynchronous creation of the frontend UI.

Workaround: Use com.intellij.xdebugger.impl.XDebugSessionImpl.runWhenUiReady.

• com.intellij.xdebugger.impl.XDebugSessionImpl#getSessionTab (internal) – deprecated and must not be used. Can also lead to race conditions.

Workaround: Use com.intellij.xdebugger.impl.XDebugSessionImpl.runWhenTabReady.

Which APIs are safe to use in Local IDE mode?

All APIs that provide data to the backend are valid and safe to use in Local mode, such as XDebugProcess, XSuspendContext, and the data they provide.

For creating debugger‑related actions, the following APIs are supported:

• com.intellij.xdebugger.impl.actions.handlers.XDebuggerActionHandler
• com.intellij.xdebugger.impl.ui.tree.actions.XDebuggerTreeActionBase
• com.intellij.xdebugger.impl.ui.tree.actions.XFetchValueActionBase

These actions should not require changes in Local IDE mode. They have been adapted to use plugin‑specific entities instead of frontend wrappers to preserve compatibility with the older implementation.

Remote Development mode migration steps

The following APIs will NOT work in Remote Development mode:

• UI and Debugger tab access:
  • com.intellij.xdebugger.XDebugSession#getUI
  • com.intellij.xdebugger.impl.XDebugSessionImpl#getSessionTab
  • com.intellij.xdebugger.impl.XDebugSessionImpl.runWhenTabReady
• Base action classes that work with debugger nodes:
  • XDebuggerTreeActionBase
  • XFetchValueActionBase

Use these alternatives instead:

• com.intellij.xdebugger.XDebugProcess.createTabLayouter – use this to provide additional tabs in the Debugger tool window.
• com.intellij.xdebugger.impl.XDebugSessionImpl.runWhenUiReady – also works for adding tabs, but com.intellij.xdebugger.XDebugProcess.createTabLayouter is the recommended approach.
• XDebuggerTreeBackendOnlyActionBase – an alternative to XDebuggerTreeActionBase that works only with XValue instead of nodes.

Subscribe to JetBrains Platform updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!