The information on this page pertains to NetBeans IDE 6.1. If you are looking for information about Ruby Debugging in 6.5, where a lot of features and enhancements have been implemented, look here.


Known NetBeans 6.1 Issue

Right version of ruby-debug-ide

There is a known bug in NetBeans 6.1. Be sure you do not have newer version then 0.1.10 of ruby-debug-ide gem installed. You can uninstall newer version with e.g.:

gem uninstall ruby-debug-ide -v '>= 0.2.0'

Otherwise NetBeans will have problem with fast debugger detection that it will not work. Fixed in 6.5.

Right version of ruby-debug-base

This bug was fixed and is available for NetBeans 6.1 via Autoupdate Center (Menu | Tools | Plugins)

There is a known bug in NetBeans 6.1. Be sure you do not have newer version of ruby-debug-base gem installed, specifically 0.10.1, by running command:

gem uninstall ruby-debug-base -v 0.10.1

Otherwise NetBeans will have problem with fast debugger</div> detection that it will not work</div>.


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-0.10.1-java.gem from debug-commons to a local directory.
2. Install the Gem into your JRuby Gem repository:

jruby -S gem install -l ruby-debug-base-0.10.1-java.gem

3. Now install ruby-debug-ide with:

jruby -S gem install --ignore-dependencies 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
  • 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.

For 6.0 on all platforms and 6.1 on Windows, it's:

  • ruby-debug-base (0.9.3)
  • ruby-debug-ide (0.1.9)

For 6.1 on Linux, it's:

  • ruby-debug-base (0.10.0)
  • ruby-debug-ide (0.1.10)

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

  • 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.

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.

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</span> 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</span> 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. You can do this by:
  • 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.

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


There are two backends supported:

  • default is the backend based on debug-commons project from RubyForge. This project is currently common effort of RDT developers (mainly Markus Barchfeld) and ours. All backend works are being done there. More on the project's pages.
  • Kent Sibilev's ruby-debug fast debugger

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.


This is the rough list of features which need to be tested. 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).

Three debuggers

  • The Fast Debugger - supposed to be used most often. More over it is the only one really usable with Rails application.
  • Pure Ruby debugger - should work seamlessly with all kind of applications. Should be tested mainly with "standard" Ruby applications/scripts.
  • JRuby debugger - there were some fixes recently in the JRuby itself which should make it usable. However not all tests in the debug-commons test suite pass so it still might have some problems. Note it is the default debugger so should work well.

Two kind of application

  • Rails Project
  • Standard Ruby application/script
  • Tests

Combination to test

Currently I would prefer following order:

  1. Rails with The Fast Debugger - I do not suppose a lot of people will test Rails with the "slow" debugger. Moreover there will be probably some warning when someone tries to debug Rails in such a way.
  2. Standard Ruby application/script with Ruby and JRuby
  3. Tests with all kinds of debuggers - this should be actually the same as with standard scripts debugging
  4. Rails Project with Ruby and JRuby
  5. Standard Ruby application/script with The Fast Debugger

It's clear that one combination is testing the others and vice versa. So it just a rough order. So by Rails debugging almost all is tested.


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
File:RubyDebugging/debugger 02.png

RHTML Debugging screenshot

Watches and Call Stack views, Baloon Evaluations

File:RubyDebugging/debugger 01.png

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