Plugin & IDE Compatibility#

Rainbow Brackets hooks deeply into IntelliJ Platform internals for bracket parsing, syntax highlighting, and editor rendering via CustomHighlighterRenderer. This tight coupling means behavior can silently break when either the plugin or the host IDE is updated, and problems typically only surface on a specific IDE build number — not just the version string. 1

How Compatibility Is Managed#

The plugin manually maintains since-build/until-build ranges: updateSinceUntilBuild = false in build.gradle.kts means these are not auto-generated. 2

The runPluginVerifier task is configured to fail only on COMPATIBILITY_PROBLEMS 3, providing a safety net for hard API breakage. The CHANGELOG.md explicitly tracks IDE compatibility per release (e.g., "Compatible with 2025.1 EAP", "Compatible with 2025.2 Release Candidate") 4 5 — confirming that each major IDE release typically requires a dedicated plugin update.

The plugin supports: IntelliJ IDEA (Ultimate/Community/Educational), PhpStorm, WebStorm, PyCharm, RubyMine, CLion, Rider, Android Studio, HUAWEI DevEco Studio, and others. 1

IntelliJ Platform 2026.3: Read Lock Prohibition During Paint#

The highest-priority active compatibility issue is a platform-level threading restriction introduced in IntelliJ Platform 2026.3.

JetBrains is forbidding acquisition of the read lock during painting to prevent UI freezes. Rainbow Brackets acquires the read lock inside a CustomHighlighterRenderer implementation to access PSI trees — this now throws a PluginException at editor paint time: 6

Attempt to take read lock was reported
The Read/Write lock is disallowed during paint.
Consider using `PsiVersioningService.freezePsiVersion` for accessing PSI trees
[Plugin: izhangzhihao.rainbow.brackets]

This was first reported against RubyMine 2026.3 EAP (build RM-263.3889.66, plugin 2026.2.0) and raises on IDE launch. 6

Required migration: A JetBrains platform engineer (@knisht) filed issue #2896 describing the fix: replace ReadAction-based PSI access in the CustomHighlighterRenderer with the new experimental API com.intellij.psi.util.PsiVersioningService#freezePsiVersion, available since 2026.2.1. 7

• Before 2026.3: freezePsiVersion is equivalent to ReadAction.runBlocking (backward-compatible).
• Since 2026.3 (or with -Dide.allow.using.frozen.psi=true): routes to a new utility that accesses a consistent PSI snapshot without acquiring the read lock — safe to call during paint.
• The YouTrack tracking issue is IJPL-250439. 7

Current status (as of 2026-09-08): The maintainer has acknowledged the issue but noted that several third-party dependencies used by Rainbow Brackets have not yet added 2026.3 support, so full 2026.3 compatibility is blocked pending upstream updates. 6

Other Common Compatibility Issue Patterns#

Regressions resolved by IDE update (not plugin update)#

Some bugs are caused by transient issues in a specific IDE patch build and resolve when the user upgrades the IDE — without any plugin change. 1 A previous example: a user on IU-261.24374.151 with plugin 2025.3.12 reported JSON bracket color mismatches that the maintainer could not reproduce; the user later confirmed it resolved after an IntelliJ update. 1

Missing dependencies after plugin update#

A plugin update can expose a missing required dependency (e.g., com.intellij.marketplace) in some IDE variants like Android Studio. This reflects a mismatch between the plugin's declared dependency list and what that IDE variant bundles. 1

EAP / pre-release IDE instability#

Running Rainbow Brackets on EAP/RC IDE builds before the plugin has a matching compatibility release is a known source of transient breakage. Check the CHANGELOG for a "Compatible with X.Y EAP" entry before using EAP builds in any active workflow. 1 8

Past read-action threading fix#

Version 2025.3.5 already fixed a related threading issue: "fix Read access is allowed from inside read-action only" for compatibility with 2025.3 EAP 1. 8 The 2026.3 issue is a stricter enforcement of the same underlying threading model.

Debugging & Reporting Guidance#

1. Check the CHANGELOG for a "Compatible with X.Y" entry matching your IDE. If absent, a compatibility release may not yet exist. 1
2. Try updating the IDE first — build-specific regressions sometimes resolve with the next IDE patch without any plugin change. 1
3. Include the full environment dump in bug reports: plugin version, IDE version, IDE build number, OS, and non-bundled plugins list. 6
4. Avoid EAP IDE builds in production unless the CHANGELOG confirms a matching compatibility update.
5. For 2026.3+ installs: The plugin is known-incompatible until the PsiVersioningService migration is complete and third-party dependencies ship 2026.3 support. There is no workaround short of staying on 2026.2.x. 6 7

Key References#