Troubleshooting the java command

This example covers common errors with using the ‘java’ command.

“Command not found”

If you get an error message like:

java: command not found

when trying to run the java command, this means that there is no java command on your shell’s command search path. The cause could be:

• you don’t have a Java JRE or JDK installed at all,
• you have not updated the PATH environment variable (correctly) in your shell initialization file, or
• you have not “sourced” the relevant initialization file in the current shell.

Refer to “Installing Java” for the steps that you need to take.

“Could not find or load main class”

This error message is output by the java command if it has been unable to find / load the entry-point class that you have specified. In general terms, there are three broad reasons that this can happen:

• You have specified an entry point class that does not exist.
• The class exists, but you have specified it incorrectly.
• The class exists and you have specified it correctly, but Java cannot it find it because the classpath is incorrect.

Here is a procedure to diagnose and solve the problem:

1. Find out the full name of the entry-point class.

- If you have source code for a class, then the full name consists of the package name and the simple class name.  The instance the "Main" class is declared in the package "com.example.myapp" then its full name is "com.example.myapp.Main".
- If you have a compiled class file, you can find the class name by running `javap` on it.
- If the class file is in a directory, you can infer the full class name from the directory names.
- If the class file is in a JAR or ZIP file, you can infer the full class name from the file path in the JAR or ZIP file.

1. Look at the error message from the java command. The message should end with the full class name that java is trying to use.

- Check that it exactly matches the full classname for the entry-point class.
- It should not end with ".java" or ".class".
- It should not contain slashes or any other character that is not legal in a Java identifier<sup>1</sup>.
- The casing of the name should exactly match the full class name.

1. If you are using the correct classname, make sure that the class is actually on the classpath:

- Work out the pathname that the classname maps to; see http://stackoverflow.com/documentation/java/3720/classpath/19816/mapping-classnames-to-pathnames#t=201609101442436616455
- Work out what the classpath is; see this example: http://stackoverflow.com/documentation/java/3720/classpath/12852/different-ways-to-specify-the-classpath
- Look at each of the JAR and ZIP files on the classpath to see if they contain a class with the required pathname.
- Look at each directory to see if the pathname resolves to a file within the directory.

If checking the classpath by hand did not find the issue, you could add the -Xdiag and -XshowSettings options. The former lists all classes that are loaded, and the latter prints out settings that include the effective classpath for the JVM.

Finally, there are some obscure causes for this problem:

• An executable JAR file with a Main-Class attribute that specifies a class that does not exist.
• An executable JAR file with an incorrect Class-Path attribute.
• If you mess up2 the options before the classname, the java command may attempt to interpret one of them as the classname.
• If someone has ignored Java style rules and used package or class identifiers that differ only in letter case, and you are running on a platform that treats letter case in filenames as non-significant.
• Problems with homoglyphs in class names in the code or on the command line.

“Main method not found in class <name>”

This problem happens when the java command is able to find and load the class that you nominated, but is then unable to find an entry-point method.

There are three possible explanations:

• If you are trying to run an executable JAR file, then the JAR’s manifest has an incorrect “Main-Class” attribute that specifies a class that is not a valid entry point class.
• You have told the java command a class that is not an entry point class.
• The entry point class is incorrect; see http://stackoverflow.com/documentation/java/5791/the-java-command-java-and-javaw/20433/entry-point-classes#t=201610061438548549287 for more information.

Other Resources

• http://stackoverflow.com/questions/18093928/what-does-could-not-find-or-load-main-class-mean
• http://docs.oracle.com/javase/tutorial/getStarted/problems/index.html

1 - From Java 8 and later, the java command will helpfully map a filename separator (”/” or ““) to a period (”.”). However, this behavior is not documented in the manual pages.

2 - A really obscure case is if you copy-and-paste a command from a formatted document where the text editor has used a “long hyphen” instead of a regular hyphen.