Runtime Classpath vs Compile-Time Classpath

This should really be a simple distinction, but I’ve been answering a slew of similar questions on Stackoverflow, and often people misunderstand the matter.

So, what is a classpath? A set of all the classes (and jars with classes) that are required by your application. But there are two, or actually three distinct classpaths:

  • compile-time classpath. Contains the classes that you’ve added in your IDE (assuming you use an IDE) in order to compile your code. In other words, this is the classpath passed to “javac” (though you may be using another compiler).
  • runtime classpath. Contains the classes that are used when your application is running. That’s the classpath passed to the “java” executable. In the case of web apps this is your /lib folder, plus any other jars provided by the application server/servlet container
  • test classpath – this is also a sort of runtime classpath, but it is used when you run tests. Tests do not run inside your application server/servlet container, so their classpath is a bit different

Maven defines dependency scopes that are really useful for explaining the differences between the different types of classpaths. Read the short description of each scope.

Many people assume that if they successfully compiled the application with a given jar file present, it means that the application will run fine. But it doesn’t – you need the same jars that you used to compile your application to be present on your runtime classpath as well. Well, not necessarily all of them, and not necessarily only them. A few examples:

  • you compile the code with a given library on the compile-time classpath, but forget to add it to the runtime classpath. The JVM throws NoClasDefFoundError, which means that a class is missing, which was present when the code was compiled. This error is a clear sign that you are missing a jar file on your runtime classpath that you have on your compile-time classpath. It is also possible that a jar you depend on in turn depends on a jar that you don’t have anywhere. That’s why libraries (must) have their dependencies declared, so that you know which jars to put on your runtime classpath
  • containers (servlet containers, application servers) have some libraries built-in. Normally you can’t override the built-in dependencies, and even when you can, it requires additional configuration. So, for example, you use Tomcat, which provides the servlet-api.jar. You compile your application with the servlet-api.jar on your compile-time classpath, so that you can use HttpServletRequest in your classes, but do not include it in your WEB-INF/lib folder, because tomcat will put its own jar in the runtime classpath. If you duplicate the dependency, you may get bizarre results, as classloaders get confused.
  • a framework you are using (let’s say spring-mvc) relies on another library to do JSON serialization (usually Jackson). You don’t actually need Jackson on your compile-time classpath, because you are not referring to any of its classes or even spring classes that refer to them. But spring needs Jackson internally, so the jackson jar must be in WEB-INF/lib (runtime classpath) for JSON serialization to work.

The cases might be complicated even further, when you consider compile-time constants and version mismatches, but the general point is this: the classpaths that you use for compiling and for running the application are different, and you should be aware of that.

8 thoughts on “Runtime Classpath vs Compile-Time Classpath”

  1. Useful post.
    I think there is a way in IDE like eclipse to export the resources while creating your jar for standalone apps.
    The jars which you have included in the build path for the project may be then exported along with the main jar, so that you dont have to put the jars separately.

  2. I’ve just started programming in Java and I’ve encountered the problem which I cannot resolve for a few days now. I was looking for a solution on the Internet, and I guess your post is closest to the issue I have. I’ve set classpath correctly (I hope. I was able to compile another programs already), but I still get the NoClassDefFoundError typing java MyProgram in the console. I’m not using any IDE, and I don’t have any .jar files either. How can I check whether my runtime classpath and compile-time classpath match?

  3. Hey I know this is off topic but I was wondering if you knew of any
    widgets I could add to my blog that automatically tweet my
    newest twitter updates. I’ve been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.

  4. Finding consumers an honest, dependable, 100% safety inspected repairs and
    service. In case you prefer that the contractor has done a remarkable job.
    Communication is the crux of the contract between the various problems.

    My web page – site (Rocco)

  5. how to find out what is the runtime and compile time classpaths ? There seems to be only one environment variable in the control panel.

  6. Thank you very much, this post saved my life, i was struggling 10 hours straight to fix this shit bug, then i found that the only problem was to add the jar in the lib directory, i live you.

  7. Thank you, finally a clear example in which the different use cases of Compile Time and Runtime classpaths are described.

    Very applicable and relatable to real world use cases.

Leave a Reply

Your email address will not be published.