Remote Debugging in IntelliJ: A Practical Guide

Remote debugging using IntelliJ IDEA offers several benefits. Using this JetBrains IDE, you get interactive breakpoints, variable inspection, and debugging integrated directly with the IntelliJ editor. However you can also introduce configuration complexity and potential security risks if you don’t get it right.

IntelliJ has become a favorite of the Bugfender team and in this post we’ll walk through the full setup, from the JVM flag to debugging inside a Docker container.

By the end, you’ll be able to:

• Catch a bug that only happens on staging.
• Step through a service you can’t run locally (this is one of the biggest pain-points we’ve found ourselves).
• Debug a containerized app without exposing it to the internet.
• Skip the mistake that freezes production traffic.

The article is designed for developers with a working knowledge of IntelliJ. If you require a different level of detail, please reach out.

What is remote debugging in IntelliJ

Remote debugging lets you attach IntelliJ’s debugger to a Java process running somewhere other than your own machine, such as a staging server, a container, even a separate process on your own laptop. You can then step through it as if it were local.

The JVM you’re debugging exposes a debug port through a startup flag. IntelliJ connects to that port over the network. From there you get full debugger access: breakpoints, variable inspection, stepping through code. No code changes required.

Compiling and running large applications on my laptop gets frustratingly slow. Since I have access to bigger and better machines, I want to compile and run on those remote servers. Benjamin Sepanski, Mythic engineer, GitHub

Problems remote debugging solves in IntelliJ

Remote debugging in IntelliJ solves a number of specific troubleshooting problems. These include investigating crashes, incorrect variable values, threading issues, performance problems, and environment-specific bugs in applications running on remote servers.

• Environment-specific bugs: something fails on staging or a teammate’s machine but works fine locally.
• Microservices you can’t run locally: spec limits make it impossible to spin up every dependent service on your own machine.
• Timing and race conditions: print statements can’t catch what only happens under real concurrent load.
• Hard-to-reproduce data: issues tied to production-like datasets you don’t have locally.

In short, remote debugging lets you investigate problems where they actually happen, rather than trying to piece them together locally. If your issue has sprung from a specific environment, distributed system, real-world workload or data that isn’t available on your development machine, this becomes especially valuable.

How to carry out remote debugging in IntelliJ

Remote debugging in IntelliJ relies on a three-step process: configure the JVM, attach the debugger, set the breakpoints. Whatever you want to debug, these three steps should remain unchanged.

First, configure the JVM for remote debugging

The IntelliJ can only attach to something if it’s got a startup flag for when the app launches.

Required JDWP agent parameters

1. Identify your point of launch. This could be a run script, a Dockerfile, a systemd service, or just a terminal command. Wherever that is, that’s where the flag goes.
2. Add the JDWP flag to that launch command. JDWP (Java Debug Wire Protocol) tells the JVM to open a port for IntelliJ to connect to.
3. Set these parameters in the flag:

Parameter	Meaning
transport=dt_socket	Connects over a network socket
server=y	The JVM listens for an incoming debugger connection
suspend=n	App starts immediately instead of waiting
address=*:5005	Host and port the debugger connects to

Choosing a host and port

1. Pick a port. 5005 is IntelliJ’s default and works for most setups. Just confirm nothing else is already using it and that your firewall allows it.
2. Set the host. Use localhost if the app runs on the same machine as IntelliJ. Use the server’s actual address if it’s remote.

Next, create a remote debug configuration

With the JVM flag ready, you need to perform the next step inside IntelliJ: set up a Remote JVM Debug configuration that knows where to connect.

Defining the name and host

1. Go to Run > Edit Configurations.
2. Add a new configuration and select Remote JVM Debug.
3. Give it a name you’ll recognize later. Something like “Staging debug” beats the default name once you have more than one of these saved.
4. Set the host and port. Use localhost if you’re connecting to your own machine, or the remote machine’s address if not. Important: The port should match what you set in the JVM flag.

Copying the generated VM arguments

1. Let IntelliJ auto-generate the VM arguments. It builds the exact argument string your target app needs, based on what you just entered.
2. Copy that string. You’ll paste it directly into whichever command or configuration you use to start the application.

Now, attach the debugger remotely

Once both sides are configured, attaching becomes a simple two-step handoff. Start the app, then connect IntelliJ to it.

1. Start your application with the VM arguments from the previous step included.
2. Watch for the listening confirmation. You’ll see a line like “Listening for transport dt_socket at address: 5005” once the app is ready for a debugger to connect.
3. Run the Remote JVM Debug configuration you created. IntelliJ connects over the network.
4. Debug as usual. From this point on, breakpoints, variable inspection, and stepping through code all work exactly like a local session.

Finally, set breakpoints in a remote session

Breakpoints work much like they do in local debugging once you’re connected.

1. Click the gutter next to any line to set a breakpoint. Execution pauses there the next time that code runs.
2. Use the same tools you’d use locally once paused: step through code, inspect variable values, and evaluate expressions live against the running process.

Remote debugging Dockerized applications

Remote debugging of Dockerized applications requires more than simply enabling the JVM debugger. The Java Virtual Machine (JVM) must expose its remote debugging port, Docker must publish and forward that port from the container to the host, and IntelliJ IDEA must connect to the correct host and port.

Here’s how to configure each part.

Exposing the debug port externally

1. Open both ports when running the container, the application port and the debug port (5005), not just the one your app normally uses. With docker run, that means two p flags:

docker run -p 8080:8080 -p 5005:5005 myapp:latest

Without that second -p 5005:5005, IntelliJ has nothing to connect to, even if the JVM inside is listening.

2. If you’re using a Dockerfile, add EXPOSE 5005 near your other EXPOSE lines. This just documents the port, it doesn’t publish it on its own. You still need the p flag above (or its equivalent in docker-compose.yml).

Updating the container entrypoint command

1. Add the same -agentlib:jdwp flag from earlier to the container’s entrypoint command, alongside the application’s normal startup command. This enables the JVM’s remote debugging interface without changing how the application itself starts. For example, if your entrypoint runs:

java -jar app.jar

it becomes:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar

2. Rebuild and restart the container so the new entrypoint and port mappings take effect. You should see the same “Listening for transport dt_socket” message in the container logs once it’s up.

Limitations of remote debugging in IntelliJ

IntelliJ remote debugging works in any environment where the JVM debug interface is enabled and reachable. However, remote debugging in production should be used with caution. Breakpoints and debugger inspection can affect application performance and availability, while exposure of the debug interface can introduce security risks.

Limitation	What it means
Remote logs aren’t automatically shown	A Remote JVM Debug configuration doesn’t automatically stream the application’s stdout/stderr or logs into IntelliJ’s Run/Debug console.
Not safe for production	Suspending a live JVM to wait for a debugger can stall real traffic
One session at a time	Most setups only support a single debugger connection per port

Our own debugging tool, Bugfender, is designed to fill these gaps. We’ve built it to capture the logs a debugger can’t reach once code is actually live. Try Bugfender free.

FAQs about remote debugging in IntelliJ

Is remote debugging safe for production?

Generally no. Beyond the security risk of exposing a debug port on a live server, pausing a JVM at a breakpoint can block real requests until you resume, which is why most production environments restrict direct network access to a debug port in the first place.

How do I disconnect without stopping the process?

Use Disconnect rather than Terminate when closing the debug session. Disconnect ends the debugger connection while the process keeps running. Terminate shuts down both the debugger and the application itself, which isn’t what you want if other people are still using it.

Where do my application logs actually go during a remote session?

They don’t go to IntelliJ. The debugger only streams breakpoints and variable data back to the IDE, not standard output. Your app’s logs land wherever they normally do, console, file, or a logging service, so check that destination directly.