The information on this page pertains to NetBeans IDE 6.5. If you are looking for information about Ruby Debugging in 6.1, look here. If about Ruby Debugging in 6.7, look here.



Bundled JRuby

Works out-of-the box.

MRI Ruby (C Ruby)

When a new debugging session is started IDE will automatically ask whether the fast debugger should be installed. Just say yes and you are done.


Automatic instalation for JRuby is not supported yet. You need to install two gems to get it working following steps below:

1. Manually download the ruby-debug-base- from debug-commons to a local directory.
2. Install the Gem into your JRuby Gem repository:

jruby -S gem install -l ruby-debug-base-

3. Now install ruby-debug-ide with:

jruby -S gem install --ignore-dependencies -v 0.4.6 ruby-debug-ide

See Troubleshooting section if you encounter problems.

What is done

You might take a look at screenshots which are sometime worth a thousand words.

Screenshots list

  • Ruby Debugging (Local Variables, Threads, Sessions and Breakpoints views, Call Stack annotations)
  • [[[RubyDebugging#RHTMLDebuggingScreenshot| RHTML Debugging]] (Watches and Call Stack views, Baloon Evaluations)

List of implemented features

  • classic-debugger support - slow, but universal, works with every Ruby compatible interpreter
  • ruby-debug support - fast, but native extension, does work only with native Ruby interpreter
  • RHTML debugging
  • Balloon Evaluation. Holding mouse over text in the editor will evaluate underlying expression and show result in the tooltip.
  • Views:
  • Local Variables
  • Global Variables
  • Watches
  • Call Stack
  • Breakpoints
  • Session (multiple debugging session, finishing, switching support)
  • Thread (state, thread switching support)
  • breakpoints management
  • line breakpoints
  • exception breakpoints
  • conditional breakpoints
  • stepping (over/into/out/resume) into project, core, loadpath classes, RHTML


When Fast Debugger does not work, first check whether correct versions of ruby-debug-ide and ruby-debug-base gems are installed.

  • ruby-debug-base (
  • ruby-debug-ide (0.4.6)

Problems during Fast Debugger installation

Be sure you have GCC installed on your Unix-like system (Linux, Mac OS X, ...). You need to install it since Fast Debugger is native C Ruby extension and needs to be compiled.

  • on Mac OS X be sure you have installed Developer Tools. They're not installed by default but they're on the install CD's you get with Leopard.
  • on Ubuntu (7.10 in the time of writing this) following packages need to be installed for compilation. Run:
sudo apt-get install build-essential autoconf

In the case you are using Ruby package from Ubuntu repository, be sure you also install ruby<version>-dev package, like ruby1.8-dev or ruby1.9-dev. Otherwise you can't compile any native extensions. E.g.

sudo apt-get install ruby1.8-dev
  • on OpenSolaris 2008.05 Run:
pfexec pkg install SUNWgcc

There's a bug where the rbconfig.rb file contains bogus paths (6705310) causing native extensions to fail to build. Prashant provides an updated rbconfig.rb via his blog, Where's my Ruby. Run:

cd /usr/ruby/1.8/lib/ruby/1.8/i386-solaris2.11
pfexec mv rbconfig.rb rbconfig.rb.orig
pfexec wget
  • be sure you have correctly set up Ruby gems. There is separate wiki page for setting up RubyGems (with special note for Fast Debugger and similar native extensions)
  • mainly you need to have sufficient permissions to your Gem repository. This might be workarounded this by installing Fast Debugger gem from command line using sudo or being logged in as root. sudo gem install ruby-debug-ide

Problems during usage - have latest pieces (Ruby, JDK)

There were few issues caused by older Rubies or JDKs, thus it is best to use latest version of:

  • native Ruby. Version 1.8.6-p36 (default on Ubuntu 7.10) contains bug which might cause Segmentation Fault error on Linux (issue 127423). Latest version (in time of this writing) is the 1.8.7. - downloadable here
  • latest version of JDK/JRE - downloadable here

Timeout problem

If you get message similar to this one:

  Cannot connect to the debugged process in 15s
  But server process is running. You might try to increase the timeout. Killing...

you might try to increase timeout by passing


to NetBeans (here to 30s). But likely there is other bug, unless you have slower computer. So if the timeout increasing does not help, follow below.

Clear userdir

Sometime there might be some misconfiguration within your current userdir. So if nothing above works another suggestion is to try to use different userdir, either deleting your current one (Help -> About to find it) or start NetBeans with alternate one, in the case the current is somehow broken. See this FAQ for more information about NetBeans userdir


If you have some very restricted firewall you might try to turn it off.

Breakpoints not getting hit

  • If you're on a Mac, make sure that the project directory doesn't have extended attributes. See this for details.
  • In a dual-boot Win/Linux system, debugging a project that resides on a Win partition does not work on Linux.

Still not working

  • The ruby-debug-ide package used by NetBeans requires that you have localhost correctly pointing to the IP address. This is normally setup correctly in all operating systems by default. However, if you experience timeouts (sometimes inconsistently) in is worth checking that your hosts file contains the setting for localhost.
  • if nothing above solved your problem, please either file a bug or let us know about your problem on NetBeans Ruby mailing lists.

Known problems

  • debugger stops on some statements like 'if', 'while' twice. This is caused by backends. To be fixed in the future.

How to file a bug

Quick link: File issue to Ruby Debugger

If you encounter any bugs and want to help killing them soon, please file a new issue into NetBeans Issuezilla -> just click this direct link to Issuezilla which fills up everything for you (you might need to login/register firstly if you are not already).

Even more helpful is to turn on the debugger-related logging and attach the log into Issuezilla as well. See following simple steps.

  1. Running NetBeans with logging turned on. In 6.7 and later you can do this by checking the Enable Detailed Logging For Debugger checkbox in Tools->Options->Misc->Ruby, in earlier versions you need to:
  • either adding the text:
    -J-Dorg.netbeans.modules.ruby.level=400 -J-Dorg.netbeans.api.ruby.platform.level=400 -J-Dorg.rubyforge.debugcommons.level=300 -J-Dorg.rubyforge.debugcommons.verbose=true

to your $NB_BIN/etc/netbeans.conf, property netbeans_default_options

  • or running NetBeans directly with those parameters, like:
    $NB_BIN/bin/netbeans -J-Dorg.netbeans.modules.ruby.level=400 -J-Dorg.netbeans.api.ruby.platform.level=400 -J-Dorg.rubyforge.debugcommons.level=300 -J-Dorg.rubyforge.debugcommons.verbose=true
  1. When NetBeans starts up, reproduce the bug, so it is logged into the log files.
  2. Then file a new issue (click this link) and attach (or just send me directly):
    1. the content of IDE log file Menu -> View -> IDE Log File (or directly $YOUR_NB_USER_DIR/var/log/messages.log)
    2. the content of the Output Window

That's all, thanks. You might want to check current issues whether the problem is not already known.

Checking debugger engine functionality

In cases when there are some problem with the debugger and it is not clear from the logs what is the culprit, it is good to test debugger engine itself from command line, to narrow the culprit to either backend or the communication with frontend (NetBeans here).

To test the engine, create a Ruby project in NetBeans Menu | File | New Project | Ruby | Ruby Application, then start a console (cmd on Windows, some terminal on Linux or Mac). Go to the directory where the project was created and start there a debugger backend with the debuggee as a parameter:

rdebug-ide _0.4.6_ -p 1234 -d -- lib/main.rb

Start other terminal and connect to debugger with telnet:

telnet localhost 1234

and type the following commands:

  • b main.rb:4
  • start
  • cont

You should see following output which show that the debugger stopped on the line 4 of the main.rb script. If not, do you something wrong is happening there, like Segmentation Fault, or any other culprit. Such info is handy to the developers, since if it does not work we know the problem is in the backend. If it does work we know that the problem is on the Java side (NetBeans or communication library).

Terminal 1:

~/NetBeansProjects/RubyApplication1$ rdebug-ide _0.4.6_ -p 1234 -d -- lib/main.rb
Waiting for connection on 'localhost:1234'
Fast Debugger (ruby-debug-ide 0.4.6) listens on localhost:1234
Starting command read loop
Processing: b main.rb:4
<breakpointAdded no="1" location="main.rb:4"/>
Processing: start
Starting: running program script
<breakpoint file="main.rb" line="4" threadId="1"/>
Stopping Thread #<Thread:0xb7df91b8>
Threads equal: true
Processing: cont
Processing context: cont
Resumed Thread #<Thread:0xb7df91b8>
Hello World

Terminal 2:

$ telnet localhost 1234
Connected to localhost.
Escape character is '^]'.
b main.rb:4
<breakpointAdded no="1" location="main.rb:4"/>start
<breakpoint file="main.rb" line="4" threadId="1"/>cont
Connection closed by foreign host.

General Architecture Overview

Ruby Debugger architecture for NetBeans consists of the following three layers:

  • backends written in C/Ruby
  • intermediate communication library written in Java, intermediating

communication between the backends and a frontend

  • frontend - NetBeans module


NetBeans utilizes debug-commons project from RubyForge. This project is common effort of RDT developers (mainly Markus Barchfeld) and ours. All backend works are being done there. More on the project's pages.

Intermediate library

It is an IDE-independent Java library intermediating communication between various Ruby debugging backends and a frontend. It is based on the one that was in RDT but with slightly remade threading part and others part refactored. Also this library will be kept and developed as part of debug-commons since it is supposed to be developed by all interested parties in the future. It uses kxml2 XML Pull Parser implementation which needs to be bundled within a frontend. To be considered whether it is really needed. Should be probably possible to use any/custom XPP implementation. I need to elaborate on this. Not a high priority though.

NetBeans frontend

Standard NetBeans module utilizing libraries/layers above.


Preferred testing platform is Windows since I'm developing and continually testing debuggers on Linux (and thus also cover - more or less; the Mac OS X).


Future works

  • remote debugging (issue #104473)
  • cross-language debugging (ruby-to-java and vice-versa - issue #135357)
  • when paused at a breakpoint, allow access to the console to send commands straight to the interpreter. This way we can query more exactly what's going and would be invaluable. (In firebug, when debugging JS, you can switch to console at any time, and interactively see what's going on)
  • ... ideas?


Ruby Debugging screenshot

Local Variables, Threads, Sessions and Breakpoints views, Call Stack annotations

RHTML Debugging screenshot

Watches and Call Stack views, Baloon Evaluations

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo