JMRI: Debugging Your Installation
This page presents an orderly method for debugging
problems that first appear when JMRI/DecoderPro is installed.
Even if you're an experienced debugger, we suggest you work
your way through these steps in order. That way, if all else
fails and you have to call for help, most of the initial
stuff will be known to be OK.
Step 1: Do you have Java installed?
Start by making sure you have an appropriate version of Java on
your system by typing
at a command prompt and looking the message that produces.
JMRI® version 4.2 requires Java 1.8.
Version 3.10.1 requires Java 1.6 or later.
Version 2.14.1 requires Java 1.5 (or 1.6 if you wish for drag & drop).
Version 2.12 requires Java 1.5 or later.
If you get a message about "command not found"
or similar, then Java is not properly installed; consult the
install pages for your
Mac OS X,
Windows computer for advice on how to fix this.
Step 2: Does the program start?
Try to start DecoderPro. (The method to do this
depends on whether you are using a
Mac OS X
computer; see the relevant page)
This tests whether the basic installations of Java and JMRI are
OK. If the program doesn't start up and run at least as far
as producing it's title screen and menus, there's something
wrong with either the JMRI installion, or perhaps with the Java
In that case, look for console messages that might describe what went
wrong. Those appear in different places:
- Mac OS X
- In the "Console" application, found in the Applications/Utilities folder, which you have to start
- In the shell window from which you started the program
- In the "Java" window; you might have to find this in the start bar
at the bottom of the screen and expand it
See if the messages tell you anything useful about missing pieces, etc. If
not, cut and paste them into an email to the jmriusers discussion list, and
somebody will help you figure out what went wrong.
Step 3: Are the Java communications libraries present?
Once the program is running, pull down the 'Edit' menu and select the
'Preferences ...' item. This opens the preferences panel.
Select the proper protocol for your layout.
At this point, do the names of one or more serial ports appear in the
selection box on the right?
If not, does your computer actually have any serial ports? You
can't use JMRI without them (Well, you can use the program, but you
can't communicate with a layout). You need to either get a serial
port, or install a
But if you have one or more serial ports, and they're not showing,
this could mean that the Java communications libraries aren't properly
installed. Check for error messages (see the note on how to
do this in Step 2 above) If you see messages about "failed to load"
or "missing class", then the communications libraries weren't found.
To fix this, please see the system-specific pages for your
Mac OS X,
Step 4: Is the communications port configured right?
For most protocols, you have to configure the baud rate, and perhaps
other options. These have to be set consistently with the layout
hardware for communications to be possible.
Step 5: Can the program talk to the layout?
The method to check whether the program can talk to the
hardware of your layout depends a little bit on what you
have installed. Basically, you want to command the system
to do something that you can see. See if each of the
Step 6: Can decoders be programmed?
Typically, this is what people want to do first. But
by going through the prior steps, we know that communications
between the program and the layout are fine, and we're
just working through the last details now.
To check this:
- Put a decoder-equipped locomotive on your programming track.
- Using your DCC throttle (not the program!) make sure you can
read the decoder's address, CV1. If so, the locomotive's connections
- On a running and configured version of DecoderPro,
select the "Single CV programmer" from the "Tools" menu.
- Enter "1" in the CV number, and click "Read"
If all goes well, you'll get a succesful read of the same address
you saw previously.
If not, check for a message. Among the possibilities are:
- No Locomotive Detected
- No Acknowledge from Locomotive
- These comes from the command
station. It means that the program was able to talk with the
command station OK, but the command station could not talk to the
locomotive. Go back to reading with the throttle and make sure
what works. If it does, try selected different programming modes
(e.g. paged, direct, etc) in DecoderPro and retrying the read.
- Timeout talking to command station
- This means that
the program didn't hear any response from the command station when it
requested the CV to be read. This is unexpected, because we found
that communications to and from the command station were OK in step 5.
Check that step again. And look for error messages that might provide
a clue (see step 3 for info on how to do that)