Starting with the 2026.2 release, there is one recommended entry point. In IntelliJ IDEA, WebStorm, and PhpStorm, opening a project that lives in WSL runs the IDE in what we call Native mode. The IDE stays a Windows application, while a small agent inside WSL handles files and processes on its behalf.

Below is how Native mode works, how our approach to WSL integration evolved to get here, and – since we tried three other approaches first – why we’re confident it’s the right foundation for your work.

What it takes to support WSL in an IDE

We’ll start with an idealized picture in which the IDE functions seamlessly inside WSL while being operated from Windows. In practical terms, “seamlessly” means you should be able to use any of the IDE’s capabilities – terminal, run and debug configurations, profiling, etc. – against a project that resides in a Linux environment. Not only that, but this must incur as little latency as possible for the coding experience to feel quick and natural, as if the project files and the IDE itself resided in a single operating-system environment.

We’ll trace how this challenge has been addressed, beginning with the earliest implementation, in which the IDE interacted with WSL through the 9P transport protocol. We will then cover Remote Development and WSLg before examining Native mode – the currently preferred mode for how IDEs work with WSL.

Toward native IDE execution in WSL

9P filesystem access and GeneralCommandLine

For the IDE to function, it needs access to the basics of a project, which are plain files. This is where the 9P filesystem protocol comes in. It provides the mechanism that allows Windows-side processes access files inside WSL. In practice, project-related file I/O performed by the IDE – scanning, indexing, archive access, and similar operations – is routed through the 9P-based filesystem layer to the Linux virtual machine.

Once file access is accounted for, the next challenge is process execution. While running on Windows, the IDE must be able to invoke tools inside WSL with the correct Linux paths, working directories, executables, environment variables, and arguments. The IDE-internal GeneralCommandLine class manages this by normalizing command execution in the WSL environment.

While this architecture enables the IDE to operate against WSL, it introduces significant trade-offs in both file access and process execution.

The 9P protocol is known to be problematic for several reasons:

• Limited symlink handling – 9P does not properly expose Linux symbolic links to Windows through \\wsl$. As a result, the IDE may detect an entry but be unable to resolve or index the linked directory tree. This affects pnpm workspaces, Python virtual environments, PHP Composer path repositories, and other environments that rely on symlinks.
• Microsoft Defender scans – on-access scanning over 9P can stretch WSL file reads by tens of seconds.
• Latency and degraded throughput – 9P-backed filesystem access adds latency, and throughput can degrade significantly, especially in workflows involving many small files. Core IDE operations such as indexing follow this pattern, generating numerous separate requests that cross the Windows/WSL VM boundary through 9P.

The situation was no less challenging on the GeneralCommandLine side. The pipeline added a maintenance burden, as developers had to account for WSL-specific execution semantics across the codebase.

As a consequence, the approach became increasingly difficult to scale and maintain, and it surfaced persistent issues with symlink handling and performance.

Running the IDE inside WSL with WSLg

What if, instead, the IDE itself resided inside WSL, close to the project it works with? This is where WSLg comes in. It provides a way to run Linux GUI applications whose visual output is integrated directly into the Windows desktop.

Here’s why we do not recommend the WSLg approach:

• From a product perspective, if the IDE is displayed on Windows, it is preferable for it to behave as a Windows-native application rather than as a Linux GUI application projected into the Windows desktop. This preserves greater control over the IDE experience and avoids dependence on an additional GUI-remoting layer.
• In a WSLg setup, the IDE may run on the native Wayland path, where JetBrains Runtime uses WLToolkit against WSLg’s Wayland compositor. This path carries known limitations in rendering, popups, window management, input methods, and desktop integration.

No first-class product experience was ever built around this setup. Although running the IDE through WSLg is technically viable, it has never been considered the preferred direction, and no dedicated out-of-the-box installation or onboarding flow was provided. It remains an ad hoc workaround rather than a supported IDE workflow.

The Remote Development approach

Another approach was Remote Development, which addressed the same fundamental challenges of file access and process execution from a different angle. Rather than extending the Windows-based IDE across the WSL boundary, it moved the IDE backend into WSL and kept only the client on Windows. This architecture solved the underlying integration problems more directly, but introduced a different set of trade-offs.

The main technical challenge of this configuration is establishing and maintaining communication between them while ensuring that the UI accurately reflects user actions and the IDE continues to function as a coherent whole. At the same time, placing the backend inside WSL provides the clear advantage of direct access to Linux files and processes.

In this setup, the two IDE parts communicate over the JetBrains RD protocol. The protocol is a structured, bidirectional stream of IDE models and events that keeps the thin client and the backend IDE logically in sync, while all heavy work, such as indexing, analysis, builds, debugging, VCS operations, and so on, happens on the backend.

The client, in its turn:

• Renders all windows and editors, and handles user input.
• Mirrors the project and editor state it receives from the backend over the RD protocol, and sends back edits, caret moves, refactoring commands, debug actions, and so on.
• Loads UI-level plugins.

The elephant in the room, however, is the cost of this split architecture. The IDE backend is a heavyweight component in its own right, requiring roughly 2 GB of additional disk space and time to download and install inside WSL. The split also introduces an inherent performance penalty, as UI-event state, user input, and other interaction data must travel continuously between the local client and the backend.

It also adds development overhead, as the code has to be split into client and server parts. Leaving specific modules undivided can cause delays and freezes in highly dynamic UIs. The associated engineering effort therefore becomes a constant and unavoidable cost.

Native mode and the IJent agent

The current design – now integrated into most of our IDEs – represents the culmination of this work and addresses many of the shortcomings of earlier approaches to WSL.

To provide access to the Linux filesystem, processes, and other environment resources without relying on 9P, GeneralCommandLine, or other second-class communication mechanisms, we developed a small agent named IJent. Because it is designed specifically for IDE scenarios, we can shape its behavior, protocol, and capabilities according to our requirements.

Together, the IDE and IJent form a client–server pair. This may resemble the Remote Development model, but the server component is much thinner and, at the same time, more versatile. Installing IJent into a WSL environment is merely one of several possible configurations; the same model can also apply to Docker and Dev Containers.

By choosing this particular technology stack, we address a broad set of concerns:

• Rust implementation – Rust keeps the executable slim. By avoiding Java/Kotlin for the agent, we eliminate additional runtime dependencies inside containers or WSL.
• Transport layer – Stdio gives us a portable, firewall-friendly transport across all environments. Hyper-V sockets on WSL offer a faster path, which is especially beneficial for large or numerous filesystem transfers.
• Correct filesystem semantics – IJent executes filesystem operations on behalf of the IDE inside the target environment. As a result, path resolution, including symbolic links, follows correct Linux semantics rather than being mediated through 9P. Third-party plugins also benefit from this model, since their file operations are routed through IJent.

EelApi: one interface for any environment

For the IDE to fully benefit from IJent, changes on the IDE side are also required. Enter EelAPI.

EelApi is an API designed to abstract away the distinction between local and remote environments for everyone writing IDE-related code – plugin authors and platform contributors alike. With EelApi, the underlying environment against which the IDE operates should no longer matter, removing the need to account for these concerns explicitly in code. In this sense, EelApi is platform-agnostic, and the IDE can remain unaware of whether it is working locally, in WSL, in Docker, or in a Dev Container.

In general, IJent implements the EelApi interface, providing the actual functionality that EelApi exposes to the IDE and plugins.

If you’re interested in a more detailed explanation of EelApi, together with a practical introduction to the topic, head over to the article The Dev Containers Story: Introducing EelApi for Plugin Authors.

What this means in practice

There are two ways to open a WSL project today:

• Opening the project directly gives you Native mode in IntelliJ IDEA, WebStorm, and PhpStorm, and more IDEs are adopting the IJent and EelApi architecture as we speak.
• The Remote Development entry point on the Welcome screen still works, but it is no longer the recommended way to open a WSL project.

We conducted performance tests in order to compare 9P mode and Native mode. The results show a clear performance gain in favor of the new approach:

Beyond performance, this architecture places development in WSL within the broader context of development in non-local environments, allowing them to be approached through the same underlying model. The same IJent agent already backs our work on Docker and Dev Containers.

Thank you for reading and for all the feedback that helped us reach this point. Tell us how Native mode holds up against your projects in the comments below.

At that point, the bug you were trying to catch is no longer the only problem. Now, you need to answer different questions:

• Which roles or authorities does the endpoint require?
• Should I just disable the security temporarily to debug the logic behind it, maybe?

Security inlays in IntelliJ IDEA are designed for that moment. Instead of updating SecurityConfig temporarily and restarting the app, or fiddling with the authentication in the HTTP test tool, you can inspect and adjust the runtime security right inside the IDE.

See What the Endpoint Requires

When a secured endpoint blocks a request, the first question is “which roles does the running app require right now for this endpoint?”

The inlay displays the role-based requirement for an endpoint – the hasRole / hasAuthority-shaped matchers that most HTTP authorization is built from. However, not every security rule can be displayed with a roles list. For example, rules defined in code in a custom AuthorizationManager show up as unknown – a single lock icon, without roles.

Seeing the actual endpoint security state is important in real Spring applications. Authorization can depend on multiple SecurityFilterChain beans, matcher order, active profiles, and conditionally registered configurations. Reading SecurityConfig classes you can find is not always the same as knowing what the running application requires.

If the roles list isn’t what you expected to see, you still need to read SecurityConfig classes anyway. So, the inlay provides a config link to the real security configuration code behind the endpoint.

Unlock the Endpoint for the Current Debug Session

When you figure out which roles the endpoint requires, the next question is: “Should I skip endpoint authorization, or resend the request with a specific authority set?” Both options are available within the unlock action in the inlay popup.

Read this before you click Unlock. Unlock acts on the running process itself, not just on requests sent from the IDE. Any client hitting that exact URI and method is affected: curl, Postman, a browser, etc. If the debugged app is reachable on your network, any request to that exact URI and method is treated as authenticated with the authorities you granted – for anyone. Unlock endpoints carefully, and re-lock or restart when you are done.

Since unlocking is a security-affecting action, it is worth mentioning what it opens and for how long:

• Scope – applies to the exact request URI and HTTP method. The concrete URI comes from the request you’re working with when you unlock – the failing request in your .http file, browser, or curl command. Unlocking GET /admin/users/42 in the IDEA HTTP Client leaves POST /admin/users/42 and GET /admin/users/99 blocked. Unlocking @GetMapping("/admin/users/{id}") in the controller code will unlock the endpoint for any {id} value.
• Layer – covers HTTP endpoint authorization only; method-level checks such as @PreAuthorize are evaluated separately (see “What Unlock Does Not Cover” below).
• Lifetime – lasts only for the running debug session, or until you lock the path again. Restarting the app clears every unlock. Both a full JVM restart and a Spring Boot DevTools in-process restart work. The unlocked paths and their authority sets live on the session and go with it.
• Persists – nothing in the app. The only thing kept is IDE-local: the username you last impersonated, per endpoint, to pre-fill on re-unlock.

So, depending on your tasks, you can do the following using the security indicator inlay:

Simple Unlock

Sometimes security is not what you are testing. You already know the endpoint is protected, but you need to reach the logic behind it. Unlocking treats the request as authenticated with the full set of roles that the endpoint requires, for that URI and method. Spring Security just sees an identity that passes and you can continue the debugging task you were doing. This is the right mode when the real tasks are:

• validate request or mapping logic in the controller;
• debug a service behind a protected route;
• a smoke test that is blocked by a local authentication setup;
• a bug reproduction you do not want to interrupt with config edits and restarts.

If the IDE cannot evaluate the roles list for the endpoint, this functionality is not available. For this case, use…

Unlock with custom authorities

The inlay popup menu also allows you to specify a username and a custom role list. Treat this as a way to test a specific authority set. It lets you check authority-based behavior behind the endpoint without creating a real account, changing test data, or going through a full SSO or token flow.

For example, you can enter the username admin with ROLE_ADMIN, ROLE_MANAGER authorities in the popup. Resend the request, and answer questions like:

• Does the controller return the expected data when the request has specified authorities?
• Is the problem in the controller logic, or in the authority set used for the request?
• How does downstream code – branching, data filtering, authority checks – behave for this exact authority set?
• Does the audit engine record a proper username – admin?

When you perform either of these actions, the request runs with an artificial Authentication in the SecurityContext, created inside the running application by the debugger with the username and roles you chose. Code that reads the authority set – via hasRole / hasAuthority checks, SecurityContextHolder.getContext().getAuthentication(), or a Principal / Authentication method parameter – sees the authorities provided by IntelliJ IDEA.

One thing to watch for: a controller parameter annotated with @AuthenticationPrincipal does not resolve for inlay-unlocked requests – it comes back null. This is a known bug, IDEA-389767, which is open and affects 2026.2 as of this writing – check it for the current status. (See “How Unlocking Works Under the Hood” below for why.)

Compared with the usual local workarounds – a permitAll dev profile, a mock authenticator, a commented-out filter – nothing rebuilds or restarts the app, and nothing stays in configuration code that could accidentally get into a production environment.

How Unlocking Works Under the Hood

Is unlocking a backdoor, or a CSRF bypass? Neither – unlock doesn’t disable or suspend anything. It treats the request as authenticated with the authorities you granted, for that exact URI and method, and lets Spring Security evaluate it from there.

If your app enforces CSRF tokens on state-changing requests, CsrfFilter runs earlier in the chain and still rejects a POST / PUT / DELETE with a missing or invalid token. So, you still need a valid token, or a CSRF-exempt setup, separately.

Unlocking is a debug-time feature. Please note that it’s an internal mechanism, not a public IDE API.

On application startup, the debugger places a hidden, non-suspending breakpoint at Spring Security’s own AuthorizationFilter – the exact spot where Spring decides whether a request is allowed. After Spring application context initialization, the IDE reads the effective HTTP authorization rules. Instead of parsing your source, the debugger reads the live SecurityFilterChain out of the running JVM to figure out what each endpoint requires. That is why the inlay shows the actual list of authorities at the HTTP layer. Clicking Unlock adds the URL, username, and roles to a set the IDE keeps for the debug session. The application code and security config are untouched.

The rest of the work happens per request, without pausing anything. When a request hits an “unlocked” URL, the execution flow passes the non-suspending breakpoint in the AuthorizationFilter. If the URL is in the “unlocked” list, the debugger adds a TestingAuthenticationToken instance to Spring’s SecurityContext. This auth object is already marked as authenticated, with the chosen username as principal and the “unlock” roles as granted authorities. Then the request goes on. Later the authorization engine reads the security context, sees the supplied authenticated principal, and evaluates it normally. For any URL you did not unlock, the breakpoint evaluation returns immediately and normal security applies.

The principal used in the auth object is the plain username String, not your app’s UserDetails or other custom principal type. That’s why a controller parameter annotated with @AuthenticationPrincipal (or any custom principal class) does not resolve for inlay-unlocked requests, as mentioned in the “Unlock the Endpoint for the Current Debug Session” chapter.

You can inject the auth object as a controller method parameter, since the artificial auth object is available through the SecurityContextHolder. So the following code should work fine:

@GetMapping("/active")

    ResponseEntity<List<Member>> getAllActive(Principal principal) {

        log.info("Auth Principal Name: {}", principal.getName());

        //...

    }

Please note that those parameters need to be declared as the base type for TestingAuthenticationToken: Principal or Authentication, not a concrete subtype. A parameter typed as JwtAuthenticationToken, for instance, throws an IllegalStateException at request time instead of resolving, because Spring MVC checks that the real principal – the injected TestingAuthenticationToken – is actually an instance of the declared type. That’s a more visible failure than @AuthenticationPrincipal‘s silent null, though the root cause is the same type mismatch. Code that depends on a concrete principal object type, token subtype, claims, credentials, or session-backed identity may still behave differently or even fail for unlocked endpoints.

Unlock hooks AuthorizationFilter, the filter behind authorizeHttpRequests and the AuthorizationManager API. This API is available since Spring Security 5.x and the non-deprecated path in 6.x. If your configuration still uses the older authorizeRequests / FilterSecurityInterceptor, that filter never runs, so unlock does not apply.

Security inlays are turned on by default, and only work while the Spring Debugger is active. You can turn them off with the spring.debugger.security.enabled flag in IntelliJ’s Registry (open it with Find Action → Registry…). Security inlays also work with a remote JVM, including a shared or staging environment. Please note that there is no log message and no actuator indicator if someone has unlocked an endpoint on the remote application. The only way to check is to look at the inlay in the editor of the attached IDE.

What Unlock Does Not Cover

Unlock works with HTTP endpoint security: rules like SecurityFilterChain URL matching, and requestMatchers() method calls. It only works on the Servlet stack, where the breakpoint is added to Spring Security’s AuthorizationFilter. It means Spring WebFlux is not supported. It uses a different class instead, AuthorizationWebFilter, which unlock does not hook (yet).

Right now, there is also no support for method-security annotations, such as:

• @PreAuthorize;
• @PostAuthorize;
• @Secured.

There is no inlay for them, no way to see what they require, and no unlock action that targets them directly.

However, the same injected Authentication is what a method security interceptor reads too. If a service method is guarded by @PreAuthorize and the authorities you injected on an unlocked endpoint satisfy it, that check passes.

Let’s have a look at the small example:

@RestController
class UserController {

    @GetMapping("/admin/users/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findUser(id);
    }
}

@Service
class UserService {

    @PreAuthorize("hasRole('ADMIN')")
    public User findUser(Long id) {
        // ...
    }
}

@Configuration
@EnableMethodSecurity
class SecurityConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated());
        return http.build();
    }
}

When you unlock GET /admin/users/{id} as ROLE_ADMIN, the call from UserController into UserService.findUser also passes the @PreAuthorize check – not because unlock targets it directly, but because the method-security interceptor reads the same SecurityContext the breakpoint already populated.

One Unlock, Several Clients

A request can come from several places: an IntelliJ IDEA .http file, a curl script, a Postman collection, or a test suite hitting your locally debugged app. If the request is rejected, don’t spend time switching to another HTTP testing tool.

For requests sent from the built-in IntelliJ IDEA HTTP Client, the security inlay sits right near the request URL in an .http file, so you don’t even need to switch to the controller code. For external clients, you’ll need to open the controller code, unlock the endpoint, and re-run the same curl or Postman request.

A Note for Automated and AI Workflows

In IntelliJ IDEA 2026.2, unlock is available in the inlay in the editor or in the .http file – it is a manual, in-IDE action. There is no programmatic switch yet, so an external script or an AI agent cannot use it on its own. We’re planning an MCP tool and a related skill that would let an agent get the roles list and perform lock/unlock actions for a selected endpoint directly, without a human in the loop. That’s aimed at the next release, 2026.3.

Until then, unlock the endpoint once from the IDE to let an agent test it. It stays unlocked for the rest of the debug session, so the agent can keep replaying curl, .http, or test requests with no further clicks. The manual step is a one-time setup, so an agent iterating on downstream controller or service logic can run unattended after it.

Conclusion

Security inlays are designed to simplify your (developer’s) life. They show the real security rules for an endpoint, and let you pass them so you can debug more easily. You can see what the endpoint requires and unlock it if needed. The request is then treated as authenticated with the authorities you choose for the debug session. All of this happens without editing SecurityConfig or restarting the app.

By applying unlock, IDEA makes a temporary security change in the running app. It opens the exact URI and method you unlocked to every client that reaches it. If you unlocked a path pattern in the controller code, it opens all paths that match the pattern.

The path stays open until you lock it again or the debug session ends. Please use it carefully, especially on an app with network access.

A few limitations are worth mentioning:

• Servlet only – Inlays and unlock hook Spring Security’s AuthorizationFilter. That filter only exists on the Servlet stack, so WebFlux isn’t supported yet.
• Debug mode only – This feature requires an active debugger session, local or on a remote JVM.
• Principal / Authentication, not a concrete subtype – Declare a controller method parameter as Principal or Authentication. A parameter annotated with @AuthenticationPrincipal comes back null. A parameter typed as a concrete subtype, like JwtAuthenticationToken, throws an error instead, because Spring MVC checks that the injected object matches the declared type.

The inlays are part of the Spring Debugger plugin for IntelliJ IDEA Ultimate, available since the 2026.2 release.

Our featured writer, Aicha Laafia, takes a closer look at upcoming JEPs and shares her key findings on what may be next for Java. Let’s dive in!

Featured Content 

Aicha Laafia

Aicha Laafia is a Java software engineer at SQLI with a love for coding, an interest in sustainability, and a commitment to empowering women in tech. She is a Women Techmakers ambassador, an Oracle ACE Associate, and part of the JetBrains Community Contributors program. When she is not coding, she enjoys exploring delicious food, phone photography, and watching Formula 1.

September is here, and so is JDK 27. Nine JEPs if you count the previews, and nothing to rewrite unless you are using preview features. Honestly? That’s my favorite kind of release. You upgrade the version, and your app gets faster.

The features that change your numbers

Compact object headers are on by default (JEP 534). Headers shrink from 96 bits to 64, cutting heap usage by 10% – 20% and pushing throughput up by 5% – 10%. G1 also becomes the default garbage collector everywhere (JEP 523), even on the small machines that used to get Serial GC instead, so check your smallest containers before you upgrade. For the full tour, Sven Woltmann wrote a solid Java 27 breakdown, and if video is more your thing, Catherine Edelveis covers the whole release here.

Two security wins that protect you by default

JFR recordings collect environment variables and system properties, which is exactly where your tokens and passwords live, so Java 27 hides them for you (JEP 536). And TLS 1.3 now gets post-quantum key exchange (JEP 527), because attackers already save encrypted traffic, waiting for quantum computers to break it later. Java 27 makes sure they can’t!

Still on Java 8 or 11?

Don’t jump, hop. Start now, LTS by LTS, and read my article Jurassic JDK: Migrate or Extinct first. I covered everything I wish someone had told me before my first migration.

Enjoy this month’s Java Annotated Monthly!

Java News

See what’s new, changing, and coming next in the world of Java:

• Java News Roundup 1, 2, 3, 4 
• Project Valhalla’s First Preview: JEP 401 Redefines == for Java Objects
• JEP 540 Proposed to Target JDK 28 with a Simple JSON API
• JSON API, Valhalla Progress, LTS ❤️ PQC – Inside Java Newscast #114
• Inside Java Episode 67 “Keeping Up With the Java Release Train” [I/O]
• JDK 27 and JDK 28: What We Know So Far
• Announcing Oracle Jipher 10.37: FIPS 140-3 Cryptography for Java
• Evolving a Java MCP Server During MCP Specification Upgrades 

Java Tutorials and Tips

Sharpen your Java skills with practical tutorials, clever techniques, and tips worth trying: 

• Persistence Workflows with IntelliJ IDEA – Andrey Belyaev | IntelliJ IDEA Tech Talks
• Resilient Sync: Your IDE Keeps Helping even when your Build is Broken
• Inside Java Episode 65 “Embracing Virtual Threads with Helidon” [I/O]
• Introduction to Retrieval-Augmented Generation with Java and MongoDB
• The Power of JDK Flight Recorder: Efficient Profiling and Troubleshooting for Java Applications
• Security Baked Into the JVM: sixteen Subjects on the wire 
• Value Classes Still Need Compiler Sympathy
• Inside Java Episode 68 “Operator Overloading with Type Classes” [AtA]
• Why is Arrays.fill 265 times slower on G1GC?
• Beyond Virtual Threads: Structured Concurrency – Balkrishna Rawool | IntelliJ IDEA Tech Talks

Kotlin Corner

Step into Kotlin Corner for fresh updates:

• When Escape Routes Become Toll Roads: Mapping How Developers Move Between Programming Languages 
• KotlinLLM is Going Open Source 
• Introducing the Kotlin Benchmark for AI Coding Agents 

AI 

Catch up on the AI ideas, tools, and experiments shaping how developers build software:

• IntelliJ IDEA Goes LSP: Java and Kotlin Intelligence Comes to VS Code, Cursor, and Agentic Flows
• JetBrains Details its First Steps to Bring Rapidly Growing AI Spend under Control
• Jakarta Agentic AI Hits Its First Milestone
• MCP Goes Stateless, and Developers Ask Whether That Just Makes it an API Again
• Top 5 AI Features in IntelliJ IDEA
• Agent Skills in IntelliJ IDEA
• Lessons Learned from Fixing Flaky Tests with Claude 
• The reality of AI in the enterprise
• How to Use AI Agents in IntelliJ IDEA With ACP
• Java Enterprise Is Already Ready for the AI Era
• Spring Office Hours Podcast: S5E20 – The Developer’s Guide to AI with Danny Thompson
• How to accelerate agentic adoption 

Languages, Frameworks, Libraries, and Technologies

Explore what’s moving and shaking across languages, frameworks, libraries, and the wider tech landscape:

• This Week in Spring 1, 2, 3, 4
• Pods as Workers, Not Agents: Rethinking the Deployment Unit for AI Agents on Kubernetes
• Gradle Is Going Agentic
• When @Immutable Made All the Difference: A 3.2x Speedup with Hibernate Second-Level Cache 
• Vibe Coding, Maven, and the Dependencies You Didn’t Choose

Conferences and Events

Mark your calendar with the conferences, meetups, and events worth showing up for:

• Kansas City Developer Conference – Kansas City, USA, September 9–12
• JCConfTaiwan – Taipei, Taiwan, September 11
• Java Forum Nord – Hannover, Germany, September 22
• JUG Saxony Day – Radebeul, Germany, September 25
• Confitura – Warsaw, Poland, September 25–26
• GOTO Copenhagen – Copenhagen, Denmark, September 28 – October 2

Culture and Community

Check out these stories about what makes the developer community tick.

• The Five Stages of AI Maturity in Engineering Organizations – Where and Why Teams Get Stuck
• From Projects to Products: Turning Platforms into Products People Use
• When Escape Routes Become Toll Roads: Mapping How Developers Move Between Programming Languages
• Culture & Methods Trends 2026: The Human Side of AI Engineering
• More Incidents Don’t Necessarily Mean Less Reliability
• What Is Reasoning
• How Code in the Age of Artificial Intelligence Becomes Write-Only and Disposable
• The Human Edge: Why Brownfield Codebases Need Mob Programming, Not Just AI Vibes
• Fast and Hard Code

And Finally…

Check out the latest articles by the IntelliJ IDEA team:

• The Grails Plugin Has a New Home: Apache Grails
• Println Debugging Done Right
• Spring Boot Configuration Management Best Practices
• Project Loom in IntelliJ IDEA: Virtual Threads, Scoped Values, and Structured Concurrency

That’s it for today! We’re always collecting ideas for the next Java Annotated Monthly – send us your suggestions via email or X by September 20. Remember to check out our archive of past JAM issues for any articles you might have missed!

You can update to this version from inside the IDE, using the Toolbox App, or by using snaps if you are a Ubuntu user. You can also download it from our website.

IntelliJ IDEA 2026.2.2 brings the following refinements:

• Loading a remote OpenAPI specification no longer fails. [IJPL-63202]
• The order of terminal tabs is now preserved after reopening a project. [IJPL-212254]
• Checkboxes in Markdown now have improved contrast for better visibility. [IJPL-93391]
• The vertical scrollbar is once again displayed correctly in the Markdown preview pane. [IJPL-251259]
• Opening directories containing a large number of .md files no longer causes the IDE to freeze. [IJPL-93385]
• Spring Modulith no longer incorrectly reports accessibility violations for types exposed through @NamedInterface in nested modules. [IDEA-376940]

To see the full list of issues addressed in this version, please refer to the release notes. 

If you encounter any bugs, please report them using our issue tracker. 

Happy developing!

Why Apache Grails

The people closest to a framework are in the best position to build its tooling. Both teams agreed that the Apache Grails project was the right home for the plugin, with the Apache Grails Project Management Committee (PMC) now overseeing development. With development in the Grails team’s hands, the plugin can evolve in line with the framework’s roadmap (including GSP tooling, GORM integration, and build toolchain updates) and follow a release cadence that the team controls. JetBrains can stay focused on core IDE and platform work while continuing to feature the plugin on Marketplace.

What’s changed

The release cadence and IDE compatibility are set by Apache Grails PMCnow, not by IntelliJ IDEA releases. Updates ship on the framework’s roadmap, and the Grails team builds, signs, and publishes them straight to Marketplace under its own vendor credentials. The PMC and community contributors are already reviewing PRs, merging fixes, and shipping releases independently. Build 262.0.0, which supports IntelliJ IDEA 2026.2, is already available.

What this means for you

Already using the plugin from Marketplace? No migration is required: Updates will continue to come from the new maintainers, and the plugin ID stays the same for now. Starting with 2026.2, however, the plugin is no longer bundled with IntelliJ IDEA Ultimate by default. If you cannot find the plugin in your IDE, install it from the Marketplace under its new Apache Grails listing. At JetBrains, we will continue to collaborate with the Apache Grails team and give them early notice of platform API changes.

Get Involved

Follow the project in the repository on GitHub, or visit the Apache Grails plugin listing on JetBrains Marketplace. Got feedback? Open an issue in the new repository or leave feedback on the Marketplace page.

We’ll keep featuring the plugin on Marketplace, and we’re looking forward to seeing where the Apache Grails team takes it from here.

Traditionally, Java concurrency has had several limitations: 

• Scalability and resource costs from blocking threads.
• Difficulty sharing contextual data between threads safely.
• Problems managing threads such as leaks and cancellation delays.
• Concurrent code that is hard to understand, debug, and maintain.

Project Loom aims to eliminate the tradeoff between simplicity and efficiency in concurrent Java code, making it easier to write, debug, profile, and maintain code that is correct, readable, and scalable. It does this through three features that work together:

• Virtual Threads (JEP 444, stable since Java 21) – Platform threads are expensive and limited in number, making highly concurrent applications resource-heavy and hard to scale. Virtual threads are lightweight and managed by the JVM, allowing many more threads to run concurrently without the same overhead.
• Scoped Values (JEP 506, stable since Java 25) – ThreadLocal variables are mutable, hard to reason about, and prone to memory leaks. Scoped values provide immutable, automatically cleaned-up data sharing that scales efficiently with virtual threads.
• Structured Concurrency (JEP 533, seventh preview in Java 27) – Unstructured concurrency leads to thread leaks, cancellation delays, and code that is difficult to debug and maintain. Structured concurrency treats a group of related threads as a single unit of work, making cancellation and error handling predictable and consistent. It also provides a clear parent-child thread hierarchy that improves observability and makes concurrent code easier to trace and inspect.

In this post, we’ll give you an overview of these features, explain some of the problems they solve, show how they work together, and demonstrate how IntelliJ IDEA supports you along the way.

Problems with Java concurrency before Project Loom

To illustrate some of the problems with concurrency and how Project Loom can solve them, let’s look at an example of how we could write concurrent code without using any of the features of Project Loom. We’ll then rewrite this code to take advantage of these features and see how they compare.

As an example, we will use an application that loads a customer profile. It fetches order history and product recommendations for a customer in parallel. You can find the project’s source code here.

The method getProfile() in the CustomerProfileService (which you can find here) loads the customer profile using CompletableFuture to run the calls concurrently:

public CustomerProfile getProfile(String customerId) throws OrderServiceException, RecommendationServiceException {
        CompletableFuture<List<Order>> orderFuture =
                CompletableFuture.supplyAsync(() -> orderServiceClient.getOrders(customerId), executor);
        CompletableFuture<List<Recommendation>> recFuture =
                CompletableFuture.supplyAsync(() -> recommendationServiceClient.getRecommendations(customerId), executor);

        CompletableFuture<Void> allFutures = CompletableFuture.allOf(orderFuture, recFuture);

        try {
            allFutures.get(2, TimeUnit.SECONDS); // single timeout covering both futures
            return new CustomerProfile(customerId, orderFuture.join(), recFuture.join());
        }

        // catch block 

The catch block handles any exceptions. This code does what it is supposed to do: It runs the independent calls in parallel, has a timeout, and makes an effort to cancel remaining tasks on failure. But there are still several potential problems:

• Thread leaks. cancel(true) marks the future as cancelled, but for CompletableFuture the interrupt flag is ignored and the work already running in the pool continues to completion unless it was explicitly wired to a cancellation signal.
• Awkward error handling. ExecutionException wraps the real cause and must be unwrapped manually (shown in the code snippet below and also available here). The unwrapping chain will need to be updated every time a new exception type is introduced.

        catch (ExecutionException e) {
            Throwable cause = e.getCause();
            orderFuture.cancel(true);
            recFuture.cancel(true);

            if (cause instanceof RestClientResponseException ex && ex.getStatusCode().value() == 503) {
                if (orderFuture.isCompletedExceptionally()) {
                    throw new OrderServiceException("Order service unavailable", e.getCause());
                }
                if (recFuture.isCompletedExceptionally()) {
                    throw new RecommendationServiceException("Recommendation service unavailable", e.getCause());
                }
            }
            throw new RuntimeException("Unexpected error", e.getCause());

• Duplicated cancellation logic. The cancel() calls are repeated across both the TimeoutException and ExecutionException catch blocks. If any additional parallel call is added later, it needs a cancel() call in both catch blocks, which is easy to forget. These blocks could drift out of sync as the code evolves.
• Fragile context propagation. Passing contextual data such as a logged-in user’s session or a trace ID across threads using ThreadLocal is fragile. ThreadLocal variables are mutable, their values persist for the lifetime of a thread unless explicitly removed, and child threads do not automatically inherit them unless you use InheritableThreadLocal, which has its own pitfalls.
• Poor observability. A thread dump shows a flat list of pool threads with no indication of which threads belong to which request, or which are still waiting on something that already failed. To see running threads, you can get a thread dump in IntelliJ IDEA when the program is suspended (either stopped at a breakpoint or paused). In the Debug tool window, click More and select Get Thread Dump while the service is handling a request.

Sidenote: To add the Get Thread Dump button to your Debugger tool window, right-click the Debugger tool window and select Customize Toolbar. In the popup, click Add, search for and select Get Thread Dump, and click OK.

Let’s take a look at how Project Loom addresses these problems.

Virtual Threads (JEP 444, stable since Java 21)

The first feature of Project Loom is Virtual Threads, which drastically improve throughput in Java applications with blocking code.  

Traditionally, the number of available threads in a Java application is limited because platform threads wrap operating system (OS) threads, and the number of OS threads is limited. Platform threads are also expensive; creating them can take milliseconds, each one consumes significant memory, and context switching between them has considerable overhead. To manage these costs, applications use thread pools – a fixed set of reusable threads managed by an ExecutorService.

In contrast, virtual threads are lightweight threads. They are cheap to create (taking microseconds instead of milliseconds), and since they are not tied to OS threads, they are not limited in number; you could run millions of them. When a virtual thread blocks, the underlying platform thread is released for other work and reassigned when the virtual thread is ready to continue. This means that virtual threads can significantly improve throughput for blocking workloads, such as I/O (anything that waits on databases, network calls, or file access), pauses, or synchronization.

In Java 24, an additional improvement was made to improve the scalability of Java code. With JEP 491: Synchronize Virtual Threads without Pinning, virtual threads that block in synchronized methods and statements release their underlying platform threads. You can see this in action in the What’s New in IntelliJ IDEA 2025.2 livestream.

We already briefly discussed virtual threads in Java 25 LTS and IntelliJ IDEA. For more information about using virtual thread dumps, have a look at Thread Dumps and Project Loom (Virtual Threads).

To debug problems with concurrent threads, check out the new, improved logpoint functionality described in Println Debugging Done Right.

Scoped Values (JEP 506, stable since Java 25)

The second feature of Project Loom is Scoped Values – a safer, more scalable alternative to ThreadLocal variables, designed with virtual threads in mind. They solve the problem of sharing contextual data across threads cleanly and safely.

To share data between components of an application, we can use thread-local variables, but these have several downsides. A ThreadLocal variable is mutable and, therefore, hard to reason about. Data persists for the thread’s lifetime unless manually removed (risking memory leaks and security issues), and child threads inherit copies that increase memory footprint.

ScopedValue provides a better model: A value is bound once within a defined scope, automatically available to all code running within that scope, and cleaned up automatically when the scope ends. The binding cannot be changed from within the scope, eliminating the risk of accidental mutation and guaranteeing that any code reading the value will see the same one. When used with structured concurrency, scoped values require no explicit propagation to child threads, making context sharing both safer and simpler.

Note that even if your code does not explicitly use ThreadLocal, frameworks like Spring use it under the hood.

For more details, see the section on Scoped Values in Java 25 LTS and IntelliJ IDEA.

Structured Concurrency (JEP 533, seventh preview in Java 27)

The third feature of Project Loom is Structured Concurrency, which is currently still in preview. Java 27 again brings some changes to this preview feature. As we have already added some support for this feature in IntelliJ IDEA, now is the perfect time to try it out.

Structured concurrency is designed to promote a style of concurrent programming that reduces common problems such as thread leaks and cancellation delays, duplicated cancellation logic, and awkward error handling. The core idea is that a group of related concurrent tasks is treated as a single unit of work with a clear owner, a clearly defined lifetime, and clear rules. Subtasks cannot outlive their scope, failures propagate cleanly, and cancellation flows automatically from parent to children.

The StructuredTaskScope lets you break a task down into concurrent subtasks that are coordinated as a single unit. Subtasks are forked to run on their own thread and joined as a unit when the work completes.

StructuredTaskScope has a factory method StructuredTaskScope.open(). This method has several overloads that allow you to provide a Joiner and/or a configuration callback. This lets you define the failure policy, a name for observability, and a timeout all in one place when opening the scope.

In our example, we want both methods (fetchOrders() and fetchRecommendations()) to succeed in order to correctly assemble the customer profile. We can provide a name for our scope and set a timeout for how long we are willing to wait on the results. If either of them fails, the other is cancelled. When a subtask fails or the timeout expires, join() throws an ExecutionException with the underlying cause. We switch on that cause to handle each case explicitly – including CancelledByTimeoutException, which is what the joiner uses to signal a timeout.

What if we don’t need results from all methods called in parallel? For example, imagine recommendations are available from two different caches and you only need the result of one of the calls to succeed. If one task succeeds, the other can be shut down. To accomplish this, we can use a different Joiner, anySuccessfulOrThrow(). As soon as one cache returns a result, the scope shuts down and the other task is cancelled automatically. If both fail, the join() method throws an ExecutionException with the exception of one of the failed subtasks as the cause.

To quickly scaffold a StructuredTaskScope in IntelliJ IDEA, use the built-in live template sts. 

Structured concurrency is still a preview feature in Java 27, so it is not yet recommended for production use. That said, the feature has been relatively stable in its broad shape for several preview rounds, with some changes to the API, and now is a great time to experiment with it. To identify where you could use structured concurrency in your code, look for places where the code performs multiple tasks in parallel and awaits the results. This code is a candidate to be rewritten using structured concurrency.

Rewriting CustomerProfileService using Project Loom features

The “modern” branch of our demo project contains the same application rewritten using the features from Project Loom. The structure follows the same pattern as before: Orders and recommendations are fetched in parallel inside the scope.

The updated method getProfile() in the CustomerProfileService (which you can find here) now uses a StructuredTaskScope:

public CustomerProfile getProfile(String customerId) throws InterruptedException, TimeoutException {
        try {
            return ScopedValue.where(CUSTOMER_ID, customerId).call(() -> {
                try (var scope = StructuredTaskScope.open(
                        Joiner.awaitAllSuccessfulOrThrow(),
                        config -> config.withName("customer-profile").withTimeout(Duration.ofSeconds(2)))) {
                    var orderTask = scope.fork(() -> orderServiceClient.getOrders(CUSTOMER_ID.get()));
                    var recTask = scope.fork(() -> recommendationServiceClient.getRecommendations(CUSTOMER_ID.get()));
                    scope.join();
                    return new CustomerProfile(customerId, orderTask.get(), recTask.get());
                } catch (ExecutionException e) {
                    switch (e.getCause()) {
                        case StructuredTaskScope.CancelledByTimeoutException _ -> throw new TimeoutException("Request timed out");
                        case OrderServiceException ose -> throw ose;
                        case RuntimeException rte -> throw rte;
                        default -> throw new RuntimeException(e.getCause());
                    }
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    throw new RuntimeException("Interrupted", e);
                }
            });
        } catch (InterruptedException | TimeoutException | RuntimeException e) {
            throw e;
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

Notice that we no longer need the duplicated cancel() calls in two catch blocks. If either task fails or the timeout is exceeded, all remaining subtasks are cancelled automatically. There is no longer any need for manual cancel() calls.

The code now clearly expresses its intent: Fetch orders and recommendations in parallel, wait up to two seconds, and fail cleanly if anything goes wrong. Because the pattern of what the code does is clearly captured in the code, this code is easier to read, understand, and reason about.

To see the difference structured concurrency makes, run the updated service in IntelliJ IDEA and take a thread dump while requests are being processed. You can create a thread dump, as described earlier. From IntelliJ IDEA 2026.1, virtual threads forked within a StructuredTaskScope are grouped into containers representing their scopes. The IntelliJ IDEA debugger now shows you the structure in structured concurrency.

Using Java 27 (EA) in IntelliJ IDEA

To try out the features described in this post, you will need Java 27. You can download it from inside IntelliJ IDEA via Project Structure | Project Settings | Project, and then open the SDK dropdown and select Download JDK. Set Version to 27 and select the Early-Access version. 

If you are using a different way to download JDKs, you can point IntelliJ IDEA to your installation. Go to Project Structure | Project Settings | Project, open the SDK dropdown, select Add JDK from disk, and point IntelliJ IDEA to your installation of Java 27.

If you’re using command-line tools like SDKMAN! or asdf, you can use inlay hints to make version management easier. If your .sdkmanrc or .tool-versions file specifies a JDK version that is not yet installed, an inlay hint will appear that allows you to download it directly. 

If the JDK is already installed but not configured for the project, you can use the inlay hint to set it as the project JDK.

For more information, see the documentation.

To get support for new language features, like structured concurrency, when using an early access version of the JDK, set the Language level to X – Experimental features.

If Java 27 has already been released when you’re reading this post, download the Java 27 distribution you want to use from IntelliJ IDEA or, if you already have Java 27 installed, point the IDE to your installation. To use structured concurrency, you also need to enable preview features. Set the Language level to 27 (Preview) – Primitive types in patterns, instanceof, and switch (5th preview) in Project Structure. IntelliJ IDEA will flag usage of preview features in the editor, so you are always aware which features are not yet stable.

Conclusion

Virtual threads, scoped values, and structured concurrency are designed as a cohesive system, each addressing a different dimension of the problem:

• Virtual Threads improve scalability. They remove the need to manage thread pool sizes and make it practical to run one thread per task, even at high concurrency.
• Scoped Values improve context propagation. This JEP solves some of the downsides of ThreadLocal (and framework workarounds), giving all tasks in a scope automatic, safe access to shared immutable context.
• Structured Concurrency solves the structural problems in concurrency by giving concurrent tasks a clear lifetime, a clear owner, and a clean failure model, thus eliminating thread leaks, duplicated cancellation logic, and ExecutionException unwrapping.

Together, they let you write concurrent code that is much easier to read than traditional concurrent code, while being safe and scalable. The boilerplate that currently may take multiple steps to get right is replaced by code that is more concise and reads exactly like the problem it is solving.

You can use these features in IntelliJ IDEA. If you have questions or feedback, please let us know in the comments below.

• Property files
• Environment variables
• System properties
• Command-line arguments

In this article, we’ll explore the best practices for managing Spring Boot application configuration.
A well-designed configuration strategy should ensure that:

• Configuration remains separate from the application code.

• The application fails to start when the required configuration is missing or invalid.

• Default values can be overridden for each deployment environment.

• Sensitive values are supplied by a dedicated secrets management system.

Configuration properties classification

Typically, Spring Boot application configuration falls into three categories:

• Application defaults: Safe, non-secret values such as third-party service URLs, timeouts, and retry limits. Store these with the application.

• Deployment configuration: Values that identify an environment, such as database hosts, queue names, and external service URLs. Supply these through the deployment platform.

• Secrets: Passwords, API keys, certificates, and private keys. Store these in a dedicated secrets system.

For example, application.properties can provide application default configuration properties:

app.promotion-service.base-url=http://localhost:8181
app.promotion-service.timeout=3s
app.promotion-service.retries=3
logging.level.com.jetbrains=DEBUG
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.open-in-view=false

A default value should be safe for every environment in which it may be used. Properties such as database URLs and credentials should never be hard-coded in the application code. If a required value has no safe default, validate its presence during startup.

Use @ConfigurationProperties for binding application properties

Spring applications can access configuration values through Environment, @Value, or @ConfigurationProperties.

Use Environment when property names must be resolved dynamically or infrastructure code needs direct access to property sources.

Use @Value for isolated values:

PromotionService(
  @Value("${app.promotion-service.base-url}") String baseUrl,
  @Value("${app.promotion-service.timeout}") Duration timeout,
  @Value("${app.promotion-service.retries}") int retries) {
    this.baseUrl = baseUrl;
    this.timeout = timeout;
    this.retries = retries;
}

Scattered @Value expressions make property names difficult to discover, validate, and refactor. A dedicated configuration type using @ConfigurationProperties supports all these features.

For related configuration properties, prefer @ConfigurationProperties. It provides:

• Type-safe binding and conversion
• Relaxed binding between property names and Java members
• Group-level validation
• IDE completion and navigation through generated metadata

For example, if we are integrating with a third-party REST API, we may want to configure the service base URL, timeout, and number of retries.

app.promotion-service.base-url=${PROMOTION_SERVICE_URL}
app.promotion-service.timeout=${PROMOTION_SERVICE_TIMEOUT:3s}
app.promotion-service.retries=3

In the above configuration, we are setting base-url value from the environment variable PROMOTION_SERVICE_URL and timeout value from the PROMOTION_SERVICE_TIMEOUT environment variable with a default value of 3 seconds.

Spring Boot supports setter-based binding. You can bind properties to a class that uses setters as follows:

@ConfigurationProperties(prefix = "app.promotion-service")
public class PromotionSvcProperties {

    private String baseUrl;
    private Duration timeout;
    private int retries;

    // Setters and getters
}

Register configuration types using @ConfigurationPropertiesScan:

@SpringBootApplication
@ConfigurationPropertiesScan
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

The @ConfigurationPropertiesScan annotation scans for @ConfigurationProperties annotated components and registers them as Spring beans.

Now we can inject PromotionSvcProperties into other Spring beans and access property values.

Prefer Records for @ConfigurationProperties binding

Typically, configuration is normally established during startup and remains unchanged for the lifetime of the application.

For most application configurations, a Java record is the preferred option. It provides immutability out of the box so that their values won’t be modified even by mistake in contrast to class-based binding where you can accidentally invoke a setter:

@ConfigurationProperties(prefix = "app.promotion-service")
public record PromotionSvcProperties(
        String baseUrl,
        Duration timeout,
        int retries) {
}

Spring Boot’s relaxed binding maps canonical kebab-case names such as base-url to the baseUrl field.

Sometimes we may want to bind properties to a bean provided by a third-party library, and we can’t change their source code to add @ConfigurationProperties annotation.

To bind configuration properties directly to a third-party class, declare it as a @Bean and annotate the bean method with @ConfigurationProperties:

@Configuration
public class ClientConfiguration {

    @Bean
    @ConfigurationProperties(prefix = "third-party.client")
    public ThirdPartyClientProperties clientProperties() {
        return new ThirdPartyClientProperties();
    }
}

You can configure the third-party.client properties as follows:

third-party.client.base-url=https://api.example.com
third-party.client.connect-timeout=5s
third-party.client.read-timeout=30s

If the third-party class is immutable or not supports setter binding, create your own properties class and use it to construct the third-party object:

@ConfigurationProperties(prefix = "third-party.client")
public record ClientProperties(
    URI baseUrl,
    Duration connectTimeout,
    Duration readTimeout
) {}


@Configuration
@EnableConfigurationProperties(ClientProperties.class)
class ClientConfiguration {

    @Bean
    ThirdPartyClient thirdPartyClient(ClientProperties properties) {
        return new ThirdPartyClient(
                properties.baseUrl(),
                properties.connectTimeout(),
                properties.readTimeout()
        );
    }
}

The wrapper approach is generally preferable because it avoids coupling your application configuration directly to the third-party library’s class structure.

Fail fast, fail early: validate configuration during startup

Configuration errors should be detected on application startup and fail fast if a configuration is missing or invalid. Add @Validated to a @ConfigurationProperties bean and apply Jakarta Bean Validation constraints to its properties.

@Validated
@ConfigurationProperties(prefix = "app.promotion-service")
public record PromotionSvcProperties(
 @NotBlank String baseUrl,
        @NotNull Duration timeout,
        @Min(1) @Max(5) int retries,
        @NotNull @Valid SyncProperties sync) {

    public record SyncProperties(@NotEmpty String cron) {
    }
}

With spring-boot-starter-validation on the classpath, binding or validation failures stop application startup. Validate required values, numeric ranges, nested groups, and other application-level constraints.

Use wrapper types when absence must be distinguished from a Java default. For example, an Integer annotated with @NotNull can identify a missing value, while an int defaults to 0.

You can also specify default values using @DefaultValue as follows:

@Validated
@ConfigurationProperties(prefix = "app.promotion-service")
public record PromotionSvcProperties(
 @NotBlank String baseUrl,
        @NotNull Duration timeout,
        @Min(1) @Max(5) @DefaultValue("3") Integer retries,
        @NotNull @Valid SyncProperties sync) {

    public record SyncProperties(@DefaultValue("0 0 * * * *") String cron) {
    }
}

In the above example, we have specified the default values for retries and cron properties using @DefaultValue which will be used in case these property values are not configured.

Understand property precedence

Spring Boot combines multiple property sources. When the same property appears in more than one source, the source with higher precedence supplies the effective value.

The following simplified order shows the sources most commonly used in application deployments, from lowest to highest precedence:

application.properties/yaml (low-precedence)
           ↓
profile-specific configuration files
           ↓
OS environment variables
           ↓
Java system properties
           ↓
command-line arguments    (high-precedence)

Spring Boot configuration loading precedence matters when troubleshooting a value that differs from the expected configuration value.

Environment variables are widely supported by operating systems, container runtimes, and cloud platforms. Spring Boot derives environment variable names from canonical property names by replacing dots with underscores, removing dashes, and converting the result to uppercase:

app.payment-timeout     -> APP_PAYMENT_TIMEOUT
spring.datasource.url   -> SPRING_DATASOURCE_URL

Determining the effective value of a property can be challenging when it is defined in multiple configuration sources. IntelliJ IDEA can display resolved configuration values as editor inlay hints. Selecting a hint identifies the property source that supplies the value and indicates whether it is overridden by another source, such as an environment variable or a system property.

IntelliJ IDEA also provides navigation between property declarations, @ConfigurationProperties members, and property usages. For custom configuration properties, this support is enhanced by the metadata generated by spring-boot-configuration-processor.

Store secrets in a dedicated system

Do not store passwords, API keys, certificates, or private keys in source control. Use a system such as HashiCorp Vault, AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault, or an equivalent platform service.

Ensure that secrets are excluded from logs, error messages, configuration metadata, and publicly accessible management endpoints.

NOTE: In non-production environments, the Actuator env endpoint can help identify the source of an effective property. It should not be exposed publicly because configuration may contain sensitive information.

Recommended configuration management

There is no single configuration-management approach that works for every application. Choose a strategy based on the application’s architecture, deployment environment, and complexity.

Monolith

For a monolithic application, keep shared defaults in the application, use profile-specific files only where necessary, and supply deployment-specific overrides through environment variables. Store sensitive values in a dedicated secret manager.

Containerized workloads

For workloads running in a container platform such as Kubernetes, keep sensible defaults in the application and provide deployment-specific configuration through ConfigMaps. Store secrets separately in a dedicated secret-management system.

Microservices

For a microservices architecture, consider Spring Cloud Config Server to centralize configuration, governance, and versioning. Continue to manage secrets through a dedicated secret-management system.

Summary

Effective application configuration starts with sensible defaults, type-safe @ConfigurationProperties, and startup validation. Keep environment-specific values outside the application, understand property-source precedence, and store secrets in a dedicated secret-management system.

The right configuration strategy should reflect the application’s architecture and deployment environment.

During local development and debugging remotely, IntelliJ IDEA helps reveal the effective configuration by showing resolved property values and their sources, highlighting overrides, and providing navigation between configuration files and bound Java properties.

The key idea is the boundary. IntelliJ IDEA remains the environment where you navigate the project, inspect code, and review changes. Across the ACP connection, each agent maintains its own models, behavior, authentication, and agent-side tools.

This makes the replaceable unit larger than an LLM. An ACP-compatible agent includes the full harness around the model: its planning logic, tools, model-routing behavior, and observability. Because ACP standardizes the boundary between the IDE and the agent, you can swap one agent for another smoothly, without changing how IntelliJ IDEA integrates with it. 

ACP in a nutshell

ACP is often described as the LSP (Language Server Protocol) for coding agents. The analogy works because the integration problem is similar.

Before the LSP, supporting each language meant writing a separate editor integration. The LSP replaced that matrix with a single contract.

ACP applies the same idea to the connection between an editor or IDE and a coding agent. Any ACP-compatible agent can connect without requiring a bespoke plugin or  private API for each pairing.

ACP originated from a collaboration between JetBrains and Zed, with both JetBrains IDEs and Zed targeted as clients from the start.

For local agents, IntelliJ IDEA starts a subprocess and communicates with it via JSON-RPC over standard input and output. During initialization, the IDE and the agent negotiate protocol versions and capabilities. Once connected, prompts flow to the agent, while progress updates, file operations, and permission requests return to the IDE.

Agents can still behave differently under that shared contract. During initialization, each one declares the optional capabilities it supports. Plans, modes, slash commands, session loading, terminal operations, and other features can differ between agents.

ACP carries the interaction between IntelliJ IDEA and the agent. Additional tools and context can reach the agent through MCP (Model Context Protocol), including user-configured servers and the integrated IntelliJ MCP server.

Start with an available agent

IntelliJ IDEA ships with several agents that require no manual ACP configuration, including Codex, Claude Agent, and Junie. Choose one and describe the task you want it to handle.

Each agent has its own workflow style, which may include a planning mode, slash commands, or a particular authentication flow. ACP lets IntelliJ IDEA host that interaction through a shared contract while preserving those differences.

Ask the agent to make a small change. After it edits a file, AI Chat shows the changed file in the conversation. Click it to open the diff in the editor beside the chat and inspect exactly what changed.

That edit-and-review loop is the part worth keeping. If you switch agents later, having the loop inside the IDE prevents you from having to move the project or review changes in a separate tool.

Install an agent from the ACP Registry

The ACP Registry contains additional ACP-compatible agents, together with the metadata IntelliJ IDEA needs to install them.

In IntelliJ IDEA, open Settings | Tools | AI Assistant | Agents and then choose an agent from the registry. The current ACP documentation describes the complete installation flow.

The agent’s configuration view also lets you expose the MCP servers configured in AI Assistant, the integrated IntelliJ MCP server, or both.

IntelliJ IDEA downloads the agent files when you apply the settings. The first session may ask you to authenticate using a method supported by that agent.

The registry also supplies the metadata used for updates and uninstallation. These operations remain in the Agents settings, so adding an agent does not require maintaining another IDE plugin.

Each registry agent retains its own license, service, credentials, and privacy terms. Check these details before granting repository access.

Connect a custom agent with acp.json

Registry agents are intended for broad distribution. An internal agent, however, often has a narrower role and should stay inside the company.

If an internal agent implements ACP, register it in ~/.jetbrains/acp.json. IntelliJ IDEA provides an Add Custom Agent action that creates and opens this file, but you can also edit the file directly.

The configuration below registers a hypothetical company migration agent:

{
  "agent_servers": {
    "Company Migration Agent": {
      "command": "/opt/company/bin/migration-agent",
      "args": ["acp"]
    }
  }
}

Each key under agent_servers becomes the agent’s display name. The command value must contain the full path to the executable that IntelliJ IDEA will start. Place the arguments required to activate that agent’s ACP mode in args; the exact values come from the agent’s documentation.

Use env when the process needs environment variables. Many agents expect you to authenticate through their CLI first and reuse credentials stored in the agent’s user configuration. If an agent accepts an API key through env, follow its documentation and avoid committing the file or its secrets to a repository.

Save acp.json and then select the configured agent in IntelliJ IDEA.

If any ACP-compatible agents are already installed on the machine, the IDE will detect them and offer to add them to the configuration.

Why use more than one agent?

Teams may want different agents for different kinds of work. ACP gives those agents a common way to connect to IntelliJ IDEA:

• Connecting an ACP-compatible agent through `acp.json` avoids developing and maintaining a separate IntelliJ IDEA plugin.
• Navigation, editing, and diff review remain in IntelliJ IDEA while developers choose the agent for the work.
• If an agent’s service or model provider is unavailable, developers can switch to another configured agent and continue working in the same IntelliJ IDEA project.

Keep the IDE, choose the agent

Use an agent already available in IntelliJ IDEA, install one from the ACP Registry, or register an internal agent in acp.json.

ACP turns the coding agent from an IDE commitment into a replaceable choice you can revisit at any time.

Some of those features are easy to miss because they are built into existing IDE actions: editing code, generating code in place, explaining selected code, working with stack traces, writing commit messages, and choosing which model or agent should handle a task. This overview focuses on five AI features in IntelliJ IDEA that are worth knowing about, with a few additional capabilities explained at the end. The list starts with one that can help before you even open the chat.

1. AI completion

You change a line, and the IDE points out the next line that needs to be changed to match. Rename a field, and it walks you to the other places that reference it, one keystroke at a time. Press Tab to jump to the spot, and Tab again to accept the edit. Ordinary completion guesses what should follow directly under your cursor. This type looks a step ahead, at the edit you haven’t made yet.

It runs on JetBrains’ own models, tuned for coding, and it stays out of your way. Fix the spacing after one comma in a parameter list, and it will offer to fix every other comma in the file. On a larger scale, this is also where full-method generation is handled – the editor has enough local shape to fill in a method body without turning the task into a chat session.

The feature is easiest to understand in small edits. Change one line, and IntelliJ IDEA suggests the next related change in the file.

2. In-editor code generation

Press Ctrl+\ anywhere in a file, type what you want in plain words, like “turn this loop into a stream” or “give me a builder for this class”, and the code appears right there at the cursor. The code lands in place, and you never have to switch to a chat to copy an answer back out of a conversation.

For a small, well-scoped change, the convenience is that the prompt starts where the edit happens. You type the instruction in the editor, review the generated code in place, and keep moving.

The generated code appears as an in-editor diff, so you can accept it, reject it, or refine the prompt. If the first version misses a constraint, add more context, ,like  “Keep the method name” or “use Optional instead of null”. IntelliJ IDEA regenerates the code with the extra information and shows the new diff in the same place.

It is the hidden gem in the list – a general-purpose prompt you can invoke at the cursor for small, arbitrary edits, without opening the AI chat or copying code back into the file.

3. AI Actions

AI Actions is the menu for people who never want to have a conversation with our model. Select a piece of code, press Alt+Enter, and choose from a variety of useful actions – no chat required.

Explain Code takes a regex you didn’t write, a SQL query someone left you, or a cron expression, and tells you in plain English what it does. Generate Unit Tests opens the tests in a diff, so you can argue with them before they land in your project. Generate Documentation writes the doc comment for a public method. These actions keep you in the file. Point at your chosen code, pick an action, and get an actionable response immediately.

4. Bring your own agent

At some point, the task stops being a single editor action. It needs file changes, tests, and a diff you can review. Through the Agent Client Protocol (ACP), you connect an external coding agent and drive it from the same place where you already inspect files, diffs, tests, and problems. Think of ACP as the LSP for agents: one protocol, so the IDE doesn’t need a custom integration for every new agent that appears next month. JetBrains’ own agent, Junie, shows up in the same registry as the third-party agents and receives no special treatment.

You ask the agent to change one endpoint. It proposes the steps, edits the service and the test, runs the test command, and leaves you with a diff you can open from the chat before accepting anything. That is the IDE part of the story. The agent can act, but the review still happens where you already review code.

Skills sit next to that. A skill is a reusable capability you set up once: triaging a CI failure, working through PR comments, converting Java to Kotlin, or nudging an agent away from the usual Spring Data JPA pagination mistake. You add skills from the + menu in the chat, and supported agents can use them without you having to retype the same long set of instructions every time.

That is where the IDE demonstrates its worth. The agent can make a series of edits, but you can inspect each one as it appears – open the affected files, check test outputs, and review diffs before accepting anything. The chat, code, and review stay in the same window, making it easier to stay in control while the agent handles the mechanical work.

5. Bring Your Own Key

Once agents are in the IDE, the next decision is more straightforward – which provider your organization allows the IDE to call. Bring Your Own Key (BYOK) enables you to add the API key or endpoint for any provider your team already uses.

A configured key can sit behind the AI chat and selected IDE features, such as commit message generation, depending on what features the provider and model support. For some teams, the ability to use a provider that has already passed internal review matters more than support for the one at the top of the current model leaderboard. 

You can configure your keys in Settings | Tools | AI Assistant | Providers & API keys. Choose a provider under Third-party AI providers, enter the key or endpoint, and test the connection. Once it is connected, the provider’s models will appear in the AI chat’s model selector.

Beyond the top five

Aside from the top five headline features, a couple of smaller capabilities are still worth knowing about because they appear where the IDE already has context.

When the stack trace is already in the console

The run console is where optimism goes for a reality check. When your app throws an error and the stack trace lands there, the Explain with AI action is on hand. The IDE reads the trace and then gives you a likely cause and a suggested fix. That is a better use of thirty seconds than pasting the top line into a search engine and opening three tabs from 2017.

When the staged diff needs a sentence

Generate Commit Message reads your staged diff and writes the message for you. Edit it, commit, and move on. It is a small feature, but it is exactly the kind you keep using once you know it exists.

The part you may have missed

The AI Chat window is still here, and has gotten more interesting with agents and skills. The easy-to-miss part is the layer of AI-powered productivity features around it: edits suggested as you type, code generated at the cursor, explanations for selected code and stack traces, and commit messages written from the staged diff.

The final effect is boring in the best way: IntelliJ IDEA, doing a little more than it used to, without making a ceremony out of it.

If you tried AI Assistant a year ago and mostly remember the chat, this is the part you may have missed.

If you are new to Agent Skills, I recommend reading AI-Assisted Java Application Development with Agent Skills first.

IntelliJ IDEA and other JetBrains IDEs include AI Assistant, which helps developers with AI agentic development. AI Assistant provides an elegant and secure way to use and manage Agent Skills.

If you missed the announcement, see Introducing the Skill Manager and Skill Repository.

In this article, we will explore:

• How to install Agent Skills via the Skills Manager.
• Managing skills with the Skill Repository.
• Installing skills globally, per project, or per agent.
• Adding your own Skill Repository.

Skills Manager

AI Assistant supports a wide range of AI agents through ACP (Agent Client Protocol).

The Skills Manager in AI Assistant lets you view the list of available skills and install them.

If you have already installed Agent Skills globally, the Skills Manager detects them and helps you install them as IntelliJ IDEA agent skills.

You can install a skill globally, at the project level, or per agent.

Skill Repositories

The Skill Repository lets you manage a list of locations where your verified skills are stored.

By default, JetBrains provides a Skill Repository hosted at https://github.com/JetBrains/skills.

These skills are verified by JetBrains for security vulnerabilities.

It is essential to check for security issues before using agent skills downloaded from the internet. A better approach is to maintain an organization-wide Skill Repository, verified by your team, and add it to the Skill Repository list.

Agent Skills in action

Based on the prompt description, the AI agent automatically detects and uses relevant agent skills.

For example, I installed spring-boot-skill, and when I asked the AI agent to write tests for Spring Boot REST API endpoints, it used the spring-boot-skill.

You can also explicitly invoke an agent skill using $skill-name [prompt] with Codex or `/skill-name [prompt]` with Claude.

Agentic Debugging using Debugger Skill

IntelliJ IDEA also includes the bundled ij-debugger skill, which teaches AI agents such as Junie, Claude, and Codex how to use the IDE’s debugger. It is particularly useful when source code analysis and logs are not enough. For example, when an incorrect value appears only at runtime, execution follows an unexpected branch, or you need to inspect variables, expressions, threads, and call stacks. The agent can start and control a debugging session, manage breakpoints, step through the code, and collect runtime evidence to identify the root cause. See Install the debugger skill to make it available to your agent.

To debug your code, describe the problem in natural language and provide any useful details, such as how to reproduce it or where you suspect the issue occurs.

For example, “A pet whose name differs only by case is not detected as a duplicate. Start a debug session, set a breakpoint in Owner.getPet(), and find out why.”

The agent sets the necessary breakpoints, runs the application, inspects the call stack and runtime values, evaluates its hypotheses, and reports its findings. Because it controls the standard IntelliJ IDEA debugger, you can follow the investigation in the Debug tool window and take over at any time.

For more details, see Agentic debugging.

Summary

AI Assistant’s Skills Manager makes agent skills part of your regular IDE workflow. You can discover, install, and manage skills without leaving IntelliJ IDEA, then make them available globally, for a specific project, or only to a particular AI agent. The AI agent can automatically select a relevant skill from your prompt, while explicit invocation gives you control when you need it.

Just as importantly, the Skill Repository provides access to skills verified by JetBrains for security vulnerabilities. Teams can also add their own repositories containing internally reviewed skills. This makes it easier to benefit from reusable agent capabilities while maintaining control over which skills developers use in their projects.

You can update to this version from inside the IDE, using the Toolbox App, or using snaps if you are a Ubuntu user. You can also download it from our website.

Here are the most notable updates:

• Markdown shell scripts now execute in the correct order. [IJPL-92206]
• Undo now works correctly after applying Optimize imports on the fly. [IDEA-285011] 
• Dragging a terminal tab after using the Move to Editor action no longer restarts the terminal session. [IJPL-165734]
• The IDE no longer throws exceptions caused by the new Resolve Conflicts mechanism for Mercurial projects.[IJPL-249379]
• Java code formatting now correctly respects the Smart tabs setting. [IDEA-388356]

To find out more details about the issues resolved, please refer to the release notes.

If you encounter any bugs, please report them to our issue tracker.

Happy developing!

There are many advanced debugging techniques, and while they all have their use cases, println debugging is still the #1 choice, whether you’re doing it manually or with the help of coding agents.

Inserting a println statement to inspect a program’s state is one of the first things novice developers do, even before they hear the word “debugging”. Years later, simple debug logging remains one of the most useful tools for diagnosing all sorts of problems in real codebases. And now, it’s also one of the favorite tools of coding agents.

Better foundation + modern workflows

The technique can be improved without losing its original simplicity. In fact, IntelliJ IDEA’s logpoints have long been a more capable superset of println debugging: While performing the same function, they can also be conditional, print stack traces, use hit counters and caller filters, be grouped, saved for later, and much more. If you try to imagine the most unusual debugging use case, chances are IntelliJ IDEA’s logpoints already have a feature for it (for example, did you know they can beep?).

In 2026.2, we’re taking logpoints further with several improvements focused less on specific use cases and more on strengthening the foundation:

• Instrumentation instead of debugger-side evaluation: IntelliJ IDEA now instruments your code directly for conditional and logging breakpoints, removing the bottleneck that other Java debuggers have.
• Agent compatibility: We’ve revised logpoints so they can be used reliably by AI agents. Together with a new bundled skill, this gives agents the guidelines and handles they need to control the debugging session and use all the logpoint features of the IDE.
• New UI and navigation: The new UI makes logpoints easier to set up. In addition, the console now tracks which println or logpoint produced each logging entry, letting you navigate there.

All these features are supported in both local and remote JVM debug sessions. 

Let’s look more closely at each of them.

A short demo

For this demo, I set up a mini gRPC server/client scenario, in which we’re supposed to debug the server side. For those new to logpoints, the next post in this series will feature a detailed tutorial based on this project. For now, let’s examine the new features.

In this particular case, suspending the app with a regular breakpoint is useless. If we try to do so, the timeout expires quickly, and execution follows the cancellation path, hiding the state we were going to inspect.

So, instead of using a breakpoint, let’s log the state, preferably with a coding agent doing it for us:

The agent not only sets the logpoints but also executes the run configurations, summarizes the resulting logs, finds the bug, and cleans up after itself.

Since IntelliJ IDEA tracks which logpoints belong to the agent, the agent cannot accidentally change yours. It does have full control over its own logpoints, though, including toggling them and modifying any properties that you can. When changing state is necessary for reproducing the bug, IntelliJ IDEA lets agents do that, but the skill steers the agent to avoid side effects and prefer logpoints whenever possible.

Here’s a short video showing how that works:

Run from the terminal

In the example above, we’re running the agent through the AI chat, but the same works equally well with agents in the built-in terminal or outside the IDE. Once the skill is installed, it becomes available in the agent of your choice:

The workflow is the same, this time with Claude Code:

Setting logpoints manually

Setting logpoints manually now takes a single click: Select the expression to log, and then click in the gutter between any two executable lines. If the expression is not in front of you in the editor, you can enter a custom expression afterwards:

To find out which piece of code produced a specific line in the console, click the line and then select Open:

IntelliJ IDEA will show the Open button that brings you to the corresponding code in the editor. Additionally, if it comes from an instrumented logpoint, the IDE will show the stack trace of how it got there – you get the same information as with the Log stack trace option, but now without cluttering the console with noisy messages.

How much faster have logpoints become?

Many benefits of logpoints are shared across debuggers:

• Logpoints do not require source changes.
• They are easy to turn on and off.
• They let you inspect code that would otherwise be inconvenient to modify.

IntelliJ IDEA’s implementation has many advantages beyond the basics, but performance is what stands out in this release.

If you’ve ever put a conditional or logging breakpoint in a hot path, you’ve seen the cost. With the traditional JPDA/JDWP breakpoint model, every hit suspends the application, evaluates the condition/log expression, and then resumes execution. For occasional hits this is fine, but in hot paths, this standard model becomes a bottleneck.

The overhead of traditional Java logpoints is not just a nuisance. The delay could hide a latency-sensitive failure, make a race condition disappear, or throttle the application load in a way that masks the problem. There’s a real risk that you would be debugging behavior introduced by the debugger itself.

Some time ago, I wrote about ways to work around this. Luckily, IntelliJ IDEA 2026.2 makes these hacks obsolete by instrumenting the debugged code for conditional and logging breakpoints. This chart shows the results of our internal benchmarking:

In our test set, the improvement is around 30x, making logpoints usable again in timing-sensitive code. You keep the same logpoint workflow, and so do agents, now with the performance of a regular print statement.

The best part is, you don’t need to do any setup to enjoy this speedup. IntelliJ IDEA will automatically detect logpoints that can be instrumented and do so behind the scenes in the same debug session, with no restart required.

Summary

Logpoints are still the same simple idea that makes println debugging great: Obtain the right bit of information and put it in the most accessible place. And with the new pieces, this technique becomes even more useful for both developers and AI agents.

More agent skills and debugger capabilities are on the way. If there is a debugging workflow you would like agents to handle, tell us in the comments under this post. And if you have a concrete feature request for IntelliJ IDEA, please file it in our YouTrack so it doesn’t go unnoticed.

Happy debugging!