Bug Bulletin: The GenomeLocPArser error in SplitNCigarReads has been fixed; if you encounter it, use the latest nightly build.

(howto) Test your GATK installation

Geraldine_VdAuweraGeraldine_VdAuwera Posts: 6,176Administrator, GATK Developer admin
edited July 28 in Tutorials

Objective

Test that the GATK is correctly installed, and that the supporting tools like Java are in your path.

Prerequisites

  • Basic familiarity with the command-line environment
  • Understand what is a PATH variable
  • GATK downloaded and placed on path

Steps

  1. Invoke the GATK usage/help message
  2. Troubleshooting

1. Invoke the GATK usage/help message

The command we're going to run is a very simple command that asks the GATK to print out a list of available command-line arguments and options. It is so simple that it will ALWAYS work if your GATK package is installed correctly.

Note that this command is also helpful when you're trying to remember something like the right spelling or short name for an argument and for whatever reason you don't have access to the web-based documentation.

Action

Type the following command:

java -jar <path to GenomeAnalysisTK.jar> --help

replacing the <path to GenomeAnalysisTK.jar> bit with the path you have set up in your command-line environment.

Expected Result

You should see usage output similar to the following:

usage: java -jar GenomeAnalysisTK.jar -T <analysis_type> [-I <input_file>] [-L 
        <intervals>] [-R <reference_sequence>] [-B <rodBind>] [-D <DBSNP>] [-H 
        <hapmap>] [-hc <hapmap_chip>] [-o <out>] [-e <err>] [-oe <outerr>] [-A] [-M 
        <maximum_reads>] [-sort <sort_on_the_fly>] [-compress <bam_compression>] [-fmq0] [-dfrac 
        <downsample_to_fraction>] [-dcov <downsample_to_coverage>] [-S 
        <validation_strictness>] [-U] [-P] [-dt] [-tblw] [-nt <numthreads>] [-l 
        <logging_level>] [-log <log_to_file>] [-quiet] [-debug] [-h]
-T,--analysis_type <analysis_type>                     Type of analysis to run
-I,--input_file <input_file>                           SAM or BAM file(s)
-L,--intervals <intervals>                             A list of genomic intervals over which 
                                                       to operate. Can be explicitly specified 
                                                       on the command line or in a file.
-R,--reference_sequence <reference_sequence>           Reference sequence file
-B,--rodBind <rodBind>                                 Bindings for reference-ordered data, in 
                                                       the form <name>,<type>,<file>
-D,--DBSNP <DBSNP>                                     DBSNP file
-H,--hapmap <hapmap>                                   Hapmap file
-hc,--hapmap_chip <hapmap_chip>                        Hapmap chip file
-o,--out <out>                                         An output file presented to the walker. 
                                                       Will overwrite contents if file exists.
-e,--err <err>                                         An error output file presented to the 
                                                       walker. Will overwrite contents if file 
                                                       exists.
-oe,--outerr <outerr>                                  A joint file for 'normal' and error 
                                                       output presented to the walker. Will 
                                                       overwrite contents if file exists.

...

If you see this message, your GATK installation is ok. You're good to go! If you don't see this message, and instead get an error message, proceed to the next section on troubleshooting.


2. Troubleshooting

Let's try to figure out what's not working.

Action

First, make sure that your Java version is at least 1.7, by typing the following command:

java -version

Expected Result

You should see something similar to the following text:

java version "1.7.0_12"
Java(TM) SE Runtime Environment (build 1.7.0_12-b04)
Java HotSpot(TM) 64-Bit Server VM (build 11.2-b01, mixed mode)  

Remedial actions

If the version is less then 1.7, install the newest version of Java onto the system. If you instead see something like

java: Command not found  

make sure that java is installed on your machine, and that your PATH variable contains the path to the java executables.

Post edited by Geraldine_VdAuwera on

Geraldine Van der Auwera, PhD

Comments

  • donfreeddonfreed BaltimorePosts: 3Member

    This article is a little out of date as GATK now requires java version 7. broadinstitute.org/gatk/guide/article?id=2846

    If you an error like this:

    Exception in thread "main" java.lang.UnsupportedClassVersionError: org/broadinstitute/sting/gatk/CommandLineGATK : Unsupported major.minor version 51.0
    

    You'll need to update to java 7

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 6,176Administrator, GATK Developer admin

    Indeed, that is correct. Thanks for reporting this, I'll update the article accordingly.

    Geraldine Van der Auwera, PhD

  • sarahhsarahh Posts: 2Member

    when I typed Java -version I had the answer java version "1.6.0_51" but when I wanted to update Java on my Mac, the Java Control Panel tells me I have the up-to date version Java 7.25. What should I do? Thanks.

  • KurtKurt Posts: 152Member ✭✭✭

    I have two Java versions going on since site wide, we have not made the transition to java 1.7. So my default is 1.6, but when I am using GATK 2.6+, I usually provide a full path (and just have it set as a variable in a shell script). e.g.

    JAVA_1_7="/isilon/sequencing/Kurt/Programs/Java/jdk1.7.0_25/bin"

    $JAVA_1_7/java -jar $GATK_DIR/GenomeAnalysisTK.jar ...

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 6,176Administrator, GATK Developer admin

    @sarahh, on MacOSX it seems that you have to install the latest JDK package from Sun (as opposed to just the JRE). It's a pain, but blame Apple...

    Geraldine Van der Auwera, PhD

  • sarahhsarahh Posts: 2Member

    Ok, I did it and it indeed changed the version to 1.7.0_25, thank you very much Geraldine!

  • hungstachungstac Posts: 2Member

    I have a Mac OSX 10.6.8 with JRE version 1.6.0_45. I tried to update to java 1.7, but according to the java website, Java 7 is not supported by versions of Mac OS X 10.6 or older. Does this mean I cannot run GATK on my computer? Thanks.

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 6,176Administrator, GATK Developer admin

    Hi @hungstac,

    If you cannot upgrade your Mac OS version, that might be a problem. There are some workarounds for this such as this one but I cannot give you any guarantees that it will work or that it is safe to do. Another workaround would be to install a virtual machine on your mac to emulate a different OS, but we can't provide any guidance for that either. I would recommend asking your IT department for help with this issue.

    Geraldine Van der Auwera, PhD

  • dfajar2dfajar2 USAPosts: 2Member

    Hi Geraldine, What if I have all the prerequisites installed to run GATK and still get an error. I am pastiing below the outputs to doublecheck they are installed.

    $ java -version

    java version "1.8.0-ea" Java(TM) SE Runtime Environment (build 1.8.0-ea-b113) Java HotSpot(TM) 64-Bit Server VM (build 25.0-b55, mixed mode)

    $ bwa

    Program: bwa (alignment via Burrows-Wheeler transformation) Version: 0.7.5a-r405 Contact: Heng Li lh3@sanger.ac.uk Usage: bwa [options] Command: index index sequences in the FASTA format mem BWA-MEM algorithm fastmap identify super-max ........

    $ htscmd

    Version: 0.0.1+ Usage: htscmd Commands: -- General and indexing tools: samview SAM<->BAM conv.........

    $ samtools

    Program: samtools (Tools for alignments in the SAM format) Version: 0.1.19-44428cd Usage: samtools [options] Command: view SAM<->BAM conversi............

    $ java -jar /usr/local/bin/picard-tools-1.101/AddOrReplaceReadGroups.jar -h

    Replaces all read groups in the INPUT file with a new read group and assigns all reads to this read group in the OUTPUT BAMVersion: 1.0 Version: 1.101(1580) Option....................

    So everything looks good, but when I try to test GATK installation I get the following error:

    $ java -jar GenomeAnalysisTK.jar --help

    ERROR ------------------------------------------------------------------------------------------
    ERROR stack trace

    java.lang.ExceptionInInitializerError at org.broadinstitute.sting.gatk.GenomeAnalysisEngine.(GenomeAnalysisEngine.java:164) at org.broadinstitute.sting.gatk.CommandLineExecutable.(CommandLineExecutable.java:53) at org.broadinstitute.sting.gatk.CommandLineGATK.(CommandLineGATK.java:54) at org.broadinstitute.sting.gatk.CommandLineGATK.main(CommandLineGATK.java:90) Caused by: java.lang.NullPointerException at org.reflections.Reflections.scan(Reflections.java:220) at org.reflections.Reflections.scan(Reflections.java:166) at org.reflections.Reflections.(Reflections.java:94) at org.broadinstitute.sting.utils.classloader.PluginManager.(PluginManager.java:79) ... 4 more

    ERROR ------------------------------------------------------------------------------------------
    ERROR A GATK RUNTIME ERROR has occurred (version 2.5-2-gf57256b):
    ERROR
    ERROR Please check the documentation guide to see if this is a known problem
    ERROR If not, please post the error, with stack trace, to the GATK forum
    ERROR Visit our website and forum for extensive documentation and answers to
    ERROR commonly asked questions http://www.broadinstitute.org/gatk
    ERROR
    ERROR MESSAGE: Code exception (see stack trace for error itself)
    ERROR ------------------------------------------------------------------------------------------

    What am I missing?

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 6,176Administrator, GATK Developer admin

    I think this is because you have Java 1.8 installed. The current version of GATK uses Java 1.7.

    Geraldine Van der Auwera, PhD

  • dfajar2dfajar2 USAPosts: 2Member

    Ha!! You were right, now I get the help screen running it with 1.7. Well, i guess it is not always the best to have the latest versions of some software installed.

    Thanks, I was turning myself crazy.

  • azaleaazalea State College, PAPosts: 1Member

    Hi, maybe this is not the right place to ask, but I was wondering how I can download GATK from the command line. I need to install GATK on a server with no GUI. Thanks.

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 6,176Administrator, GATK Developer admin

    Hi @azalea,

    That's not currently possible, sorry. You'll need to download it on a workstation with a GUI then transfer it over your network to your server.

    Geraldine Van der Auwera, PhD

  • egeulgenegeulgen USPosts: 3Member

    Hey @dfajar2 I've got to same problem. How did you work around it? uninstall 1.8 and 1.7?

    @dfajar2 said: Ha!! You were right, now I get the help screen running it with 1.7. Well, i guess it is not always the best to have the latest versions of some software installed.

    Thanks, I was turning myself crazy.

  • egeulgenegeulgen USPosts: 3Member

    @dfajar2 nevermind, I figured it out

    @egeulgen said: Hey dfajar2 I've got to same problem. How did you work around it? uninstall 1.8 and 1.7?

    Thanks, I was turning myself crazy.

  • iqbaliqbal Olso university hospitalPosts: 4Member
    edited April 28

    Hi, I have installed the java 1.7 but it still shows the older version in my mac os 10.9.2, can you help?

    Post edited by iqbal on
  • iqbaliqbal Olso university hospitalPosts: 4Member

    well, i have found the solution to my problem...

  • cgarner4cgarner4 Posts: 3Member

    Hello :o)

    I understand that the article is a bit outdated so I may not get the same out put shown in the example. What I am getting seems very similar but I am concerned about the error in the first line:

    Error: -jar requires jar file specification Usage: java [-options] class [args...] (to execute a class) or java [-options] -jar jarfile [args...] (to execute a jar file) where options include: -d32 use a 32-bit data model if available -d64 use a 64-bit data model if available -server to select the "server" VM The default VM is server, because you are running on a server-class machine.

    -cp <class search path of directories and zip/jar files>
    -classpath <class search path of directories and zip/jar files>
                  A : separated list of directories, JAR archives,
                  and ZIP archives to search for class files.
    -D<name>=<value>
                  set a system property
    -verbose:[class|gc|jni]
                  enable verbose output
    -version      print product version and exit
    -version:<value>
                  require the specified version to run
    -showversion  print product version and continue
    -jre-restrict-search | -no-jre-restrict-search
                  include/exclude user private JREs in the version search
    -? -help      print this help message
    -X            print help on non-standard options
    -ea[:<packagename>...|:<classname>]
    -enableassertions[:<packagename>...|:<classname>]
                  enable assertions with specified granularity
    -da[:<packagename>...|:<classname>]
    -disableassertions[:<packagename>...|:<classname>]
                  disable assertions with specified granularity
    -esa | -enablesystemassertions
                  enable system assertions
    -dsa | -disablesystemassertions
                  disable system assertions
    -agentlib:<libname>[=<options>]
                  load native agent library <libname>, e.g. -agentlib:hprof
                  see also, -agentlib:jdwp=help and -agentlib:hprof=help
    -agentpath:<pathname>[=<options>]
                  load native agent library by full pathname
    -javaagent:<jarpath>[=<options>]
                  load Java programming language agent, see java.lang.instrument
    -splash:<imagepath>
                  show splash screen with specified image
    

    See http://www.oracle.com/technetwork/java/javase/documentation/index.html for more details.

    Can anyone offer feedback on this? Thanks,, in advance!

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 6,176Administrator, GATK Developer admin

    @cgarner4‌ It sounds like you forgot to specify the -jar file in your command... See the basic GATK command line structure in the docs.

    Geraldine Van der Auwera, PhD

  • filipzembolfilipzembol Czech republicPosts: 1Member

    Hi I would like to install new version of GATK. I download it and unpack it. after that I used: java -jar GenomeAnalysisTK.jar --help An I received: Exception in thread "main" java.lang.UnsupportedClassVersionError: org/broadinstitute/gatk/engine/CommandLineGATK : Unsupported major.minor version 51.0 at java.lang.ClassLoader.defineClass1(Native Method) at java.lang.ClassLoader.defineClass(ClassLoader.java:643) at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142) at java.net.URLClassLoader.defineClass(URLClassLoader.java:277) at java.net.URLClassLoader.access$000(URLClassLoader.java:73) at java.net.URLClassLoader$1.run(URLClassLoader.java:212) at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findClass(URLClassLoader.java:205) at java.lang.ClassLoader.loadClass(ClassLoader.java:323) at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:294) at java.lang.ClassLoader.loadClass(ClassLoader.java:268) Could not find the main class: org.broadinstitute.gatk.engine.CommandLineGATK. Program will exit.

    Please could you help me where is the problem?

  • thibaultthibault Posts: 19GATK Developer mod
    edited July 15

    Unfortunately this is a Java error so we can't control this confusing message.

    What it means is that you need to upgrade to Java 7 (also known as Java 1.7).

    Post edited by thibault on

    Joel Thibault ~ Software Engineer ~ GSA ~ Broad Institute

Sign In or Register to comment.