Debugging Scala code with simple-build-tool (sbt) and IntelliJ

What's the easiest way to debug Scala code managed by sbt using IntelliJ's built-in debugger? The documentation from "RunningSbt" from sbt's google code site lists commands for running the main class for a project or the tests, but there seem to be no commands for debugging.

Follow-up question: what's the easiest way to attach IntelliJ's debugger to Jetty when using sbt's jetty-run command?

There's a very convenient -jvm-debug flag in the official SBT packages for Mac, Linux & Windows. You can use the flag to specify the debug port:

sbt -jvm-debug 5005

Under the covers, this starts the JVM for SBT with the typical verbose debugging incantation:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

You now can run your code as normal, for example with the sbt run command.

Configuring IntelliJ to connect to the running code...

Now you connect IntelliJ to your running process using a Remote Debug configuration. Note that the upper 3 fields in this form, while scary, are just for you to copy text out of, rather than into (they're giving the verbose debugging incantation specified above, which -jvm-debug already takes care of for you) - the only configuration you can change is in the Settings section halfway down:

For ordinary debugging in IntelliJ, you can use an Application run/debug configuration in the usual way, regardless of whether you're using sbt to compile your code.

To connect to your application running in Jetty, you'll need to create a Remote debug configuration. When you do so, IntelliJ will give you a set of command line arguments for running the remote JVM -- something like

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

Launch sbt with these arguments and then execute jetty-run. Finally, launch your remote debug configuration in IntelliJ. This thread might be useful.

I had some trouble with this too, so at the risk of being overly detailed, here's what I did:

SETUP

1. Create a run configuration for sbt jetty-run

• Go to Run > Edit Configurations
• Click the [+] icon and choose Scala Compilation Server
• Enter whatever name you want, and click the "Run SBT Action" checkbox and select the SBT Action jetty-run from the [...]

2. Create a debug configuration for remote debugging

• Go to Run > Edit Configurations
• Click the [+] icon and choose Remote
• Enter whatever name you want and copy the line -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005 (make sure to click OK to actually create the configuration)

3. Set up sbt plugin to run the vm options above

• Go to File > Settings > SBT
• Paste the line -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005 in the VM parameters box, after the ones that are already there

DEBUGGING

1. Set breakpoints as desired
2. Start the jetty web server by choosing the sbt jetty-run configuration you created above and choosing Run > Run or by clicking the green arrow
3. Start the remote debugger by choosing the remote debugging configuration you created above and choosing Run > Debug or by clicking the bug icon

This one works for me every time, and the only thing you need to set up is remote debugging in IntelliJ; I start up SBT with JVM parameters from the terminal in IntelliJ:

sbt -J-Xdebug -J-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

After that I can start remote debugging on localhost:5005

None of these answers or provided links worked for me, so once I figured this out, I figured I'd share...

including the background understanding I didn't have when I started...

This is based mostly on the instructions here just with additional explanation that carried me through it.

My Environment: Scala 2.10.2, SBT 0.13, and IntelliJ 13.1

Background: >- For whatever reason, using SBT to compile Scala in IntelliJ isn't integrated the way Maven projects are (which allow debugging really easily). >- It appears from my understanding that when compiling with SBT, you're compiling in a separate process, therefore, you need to be remotely debugging.

What is Debugging? >- Debugging is a mode you can run your JVM or app in that allows you to control the flow of code execution. >- The Debugging Tool you use can then issue commands to the Debugging Engine that tells it "execute the next line of code then pause again" or "continue executing" or "get the value of the variable stored here in memory".

What is Remote Debugging? >- Remote Debugging is debugging over a network connection (socket). >- This network connection allows you to issue the commands to the Debug Engine from a remote machine. >- This is useful for when you want to debug code that's running on a remote server, BUT >- It's also useful for situations like Scala code running under SBT and launching via a web server, such as Jetty or Tomcat, separate from your IntelliJ environment.

Referencing the link above, the following explanations/modifications are useful: >1. Setup IntelliJ to launch SBT with the "enable debugging" JVM settings, including the port to use when setting up the network socket. (unchanged) add the named VM parameters to your IntelliJ settings. >2. Ensure your port number here matches your JVM settings from Step 1. >3. When you launch SBT, you need to do it from the SBT Console plugin (which is what you configured in Step 1). If you're running SBT outside of IntelliJ (at the commandline), you'll need to launch SBT with the same VM parameters from Step 1 (I didn't do this; so no instructions). After this step, SBT is now running (but your code is not yet) and the JVM is setup for Remote Debugging. >4. This starts the IntelliJ Debugging Tool, which connects to the JVM you started in Step 3. >5. Finally, you start the compilation in the SBT Console. You can do this with any compilation command, including a continuous compilation command. If continuous re-compile, the recompile will happen, but not while code execution is paused by the debugger.

I am adding another answer here, because I found this question when looking up a related problem: Debugging test classes using breakpoints.

I am using ScalaTest, and I typically run a suite using sbt's 'test-only' command. Now when I want to use the interactive debugger, I can do the following:

Create a new Run/Debug Configuration of type 'ScalaTest', put the main "Test Class:" name, and choose "Before launch: Run SBT Action 'test-compile'". That's it, you can place breakpoints now in the test sources, and run this configuration.

I've been struggling with debugging too on Windows with a Spray-can / Akka / Scala app built via SBT, using Intellij. Piecing together various suggestions, the simplest approach for me was:

1. Make sure you have sbt.Revolver in your project/plugsin.sbt file e.g.

   addSbtPlugin("io.spray" % "sbt-revolver" % "0.7.1")

2. Set javaoptions in you build.sbt file:

javaOptions := Seq("-Xdebug", "-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005")

In particular use the suspend=y option. This will hold the app until you connect a remote debugger from Intellij

3. Set up a debugger configuration in Intellij via Run / Edit Configurations menu. Press the + button, select the "Remote" option. Make sure the entries match the javaoptions above, in particular the port address of 5005. Give the config a name like 'Spray'.

4. From your SBT console use the re-start command. You should see the 5005 port address in the feedback output.

5. In Intellij set your breakpoints.

6. From Intellij, select the Run \ Debug 'Spray'. This should connect to the spray-can web server. You should be able to see a lot of threads in the debug window.

7. Beware that some of the Get directives in Spray seem to get executed on start up but not repeatedly on calling the website.

For what it's worth Windows folk, edit %SBT_HOME%\bin\sbt.bat and locate the following lines of code:

:run

"%_JAVACMD%" %_JAVA_OPTS% %SBT_OPTS% -cp "%SBT_HOME%sbt-launch.jar" xsbt.boot.Boot %*
if ERRORLEVEL 1 goto error
goto end

then replace them with this code:

FOR %%a IN (%*) DO (
  if "%%a" == "-jvm-debug" (
    set JVM_DEBUG=true
    set /a JVM_DEBUG_PORT=5005 2>nul >nul
  ) else if "!JVM_DEBUG!" == "true" (
    set /a JVM_DEBUG_PORT=%%a 2>nul >nul
    if not "%%a" == "!JVM_DEBUG_PORT!" (
      set SBT_ARGS=!SBT_ARGS! %%a
    )
  ) else (
    set SBT_ARGS=!SBT_ARGS! %%a
  )
)

if defined JVM_DEBUG_PORT (
  set _JAVA_OPTS=!_JAVA_OPTS! -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=!JVM_DEBUG_PORT!
)

call :run %SBT_ARGS%

if ERRORLEVEL 1 goto error
goto end

:run
"%_JAVACMD%" %_JAVA_OPTS% %SBT_OPTS% -cp "%SBT_HOME%sbt-launch.jar" xsbt.boot.Boot %*
goto :eof

Best I can do to get same behaviour for -jvm-debug when seen in the Bash script launcher

NB. I don't think %SBT_HOME% actually exists outside this script, unless you created explicitly in you environment, but anyway you get the point :D

File->Settings->Other Settings->SBT VM parameters -Xmx512M -XX:MaxPermSize=256M -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

Run->Edit Configurations Press + and then select remote Press Apply

Now in the SBT console (Started inside by intelliJ) when you execute the command 'run' You will see "Listening for transport dt_socket at address: 5005"

Now press Run->Debug. You will see the debug menus below activated. It has two tabs Debugger and Console.

Use F7 to from next line to next

I chose suspend to be n. With it being y when I ran the run command it was stuck

export SBT_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5009

try this

AttachMe IntelliJ plugin is potentially faster way off attaching the debugger without having to fiddle with port numbers:

> AttachMe will attach the IntelliJ debugger automatically even if you > start your app from terminal (or any other way). You don't need to > trigger Attach to process action manually.

Blog post and readme have setup instructions, however I had to alter them a bit to get it working on my machine

1. Download installer.sh script from official repo

   curl -o installer.shhttps://raw.githubusercontent.com/JetBrains/attachme/master/installer.sh
   

2. Give it executable permissions chmod u+x installer.sh

3. Run it with ./installer.sh

4. This should install the agent under /.config/attachme/agent.jar and create ~/.attachme file

5. Modify ~/.attachme to contain

   AM_JDWP_ARGS="transport=dt_socket,server=y,suspend=y,address=127.0.0.1:0"
   echo Using JDWP arguments ${AM_JDWP_ARGS}
   export JAVA_TOOL_OPTIONS="- javaagent:/Users/mario_galic/.config/attachme/agent.jar -agentlib:jdwp=${AM_JDWP_ARGS}"
   echo "AttachMe configured successfully"
   

6. Install corresponding Attachme plugin and restart: IntelliJ | Preferences | Plugins

7. Create Attachme run configuration: Run | Edit configurations... | Add new configuration | Attachme debugger registry | OK

After these one-off shenanigans, we can attach a debugger automatically by

1. Start Attachme run configuration
2. source ~/.attachme
3. Start application from terminal, perhaps, sbt "runMain example.Hello"
4. The debugger should automatically attach and stop at any breakpoint

I also got the same problem, I like to share how I resolved. By the way I am using Ubuntu 14.04 and IntelliJ 15.

1. In Setting -> SBT -> Pasted below line in VM Parameters text box:

   -XX:MaxPermSize=384M -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

2. Opened Termilal in IntelliJ and run:

   sbt -jvm-debug 5005

Note: you should see this line in terminal: "Listening for transport dt_socket at address: 5005"

3. Edit Configurations -> Click + -> Select 'Remote'

    I. Give some name example: DebugMyModule
   
    II. All needed configurations will be set automatically, But you just verify. In Command line arguments should look like this "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005".
   
    III. In 'Search Sources in Module's Classpath' text box specify your module in which module your test cases are there.
   
    IV. put 127.0.0.1 host instead of 'localhost'. 'localhost' not working for me.
   

4. Select DebugMyModule in Edit Configurations list box and click Debug.

Note: You should see Debug View opened and in Debug Console You should able to see "Connected to the target VM, address: '127.0.0.1:5005', transport: 'socket'"

5. Put breakpoints in few test cases in your Testclass.

6. Come to Terminal where you run "sbt -jvm-debug 5005" and run like below

    project <your-module-name>
    it:testOnly package.TestSpec
   

For example: com.myproject.module.AddServiceTest[Spec]

7. You can see debug started in your test case breakpoint.

Give a cent step by step regarding a relatively new version of Intellij (2020.1.4):

• Configure Intellij

  • "Edit Configurations"
    
  • Add "Remote"
    This new version of Intellij does not allow you to edit the string in the "Command line arguements", you can only edit the "Host" and "Port" above, which I leave it default; I only change the "module path" below to "root" (not sure if it's necessary)

• Remote debug

  • Set your break point
  • Execute sbt command in command line, e.g. sbt -jvm-debug 5005 test
  • Immediately go back to Intellij and click on "Debug", it should show something like "Connected to xxx", then wait till it suspends at your break point
    

As per Roberto Tyley's answer above, but in Windows we also need to set the following environment variables after installing sbt:

SBT_HOME C:\Program Files (x86)\sbt\
[or wherever sbt is installed]

SBT_OPTS -Xdebug -runjdwp:transport=dt_socket,server=y,suspend=n,address=5005

[per RT's IntelliJ example]

Add to path: %SBT_HOME%\bin;%SBT_OPTS%

Then run the following in the command line within the project folder "sbt run -jvm -debug 5005".

If this is working properly, the command line will initially output a line re "Listening for transport dt_socket at address: 5005".

Set breakpoint in IntelliJ.

Open website in browser to trigger the debugger breakpoint e.g. "http://localhost:9000/";.