class loaders

the picture

you know that ClassCastException: class Greeter cannot be cast to class Greeter? it reads like the JVM is broken. it isn't: those really are two different classes that happen to share a name.

think of a library system with three branches: the central archive (bootstrap), the city library (platform), and your neighbourhood branch (app). you always ask at your local branch, but the rule is that each branch first phones the one above it: "do you have this?". only if the answer is no does the local branch check its own shelves. that's why the archive's copy of a famous book always wins over anything your branch has: you can't shadow the classics. and if two branches each print their own copy of a book, those are two different copies, even if every page is identical.

the three loaders

void main() {
    IO.println(String.class.getClassLoader());
    IO.println(java.sql.Connection.class.getClassLoader().getName());
    IO.println(ClassLoader.getSystemClassLoader().getName());
    IO.println(ClassLoader.getSystemClassLoader().getParent().getName());
}

null
platform
app
platform

null is how java spells "bootstrap": that loader is part of the JVM's C++ code and has no java object. and which modules belong to which loader isn't a secret, you can just ask ModuleLayer.boot(). here's jdk 25, launched from the classpath:

parent delegation

when a loader is asked for a class it hasn't loaded yet, it delegates to its parent first. only when the parent (and its parent) can't find it does it search its own sources.

delegation is why you can't break the JDK by putting your own java/lang/String.class on the classpath: the app loader asks bootstrap first, and bootstrap always has the real one. and if you write a loader that tries to define a class in java.* itself, the JVM refuses outright:

Exception in thread "main" java.lang.SecurityException: Prohibited package name: java.lang
	at java.base/java.lang.ClassLoader.preDefineClass(ClassLoader.java:847)

a class is (name, loader)

the JVM identifies a class by its binary name and its defining loader. two loaders can define a class with the same name from the very same bytes, and the JVM treats them as unrelated types. here it is, for real: compile Greeter into a temp directory, then load it through two separate URLClassLoaders.

import java.net.URL;
import java.net.URLClassLoader;
import java.nio.file.Files;
import java.nio.file.Path;
import javax.tools.ToolProvider;
 
void main() throws Exception {
    // write Greeter.java to a temp dir and compile it there (not on our classpath)
    Path dir = Files.createTempDirectory("greeter");
    Path src = dir.resolve("Greeter.java");
    Files.writeString(src, "public class Greeter { public String hi() { return \"hi\"; } }");
    ToolProvider.getSystemJavaCompiler().run(null, null, null, src.toString());
 
    URL[] path = { dir.toUri().toURL() };
    Class<?> a = new URLClassLoader(path).loadClass("Greeter");
    Class<?> b = new URLClassLoader(path).loadClass("Greeter");
 
    IO.println("same name:  " + a.getName().equals(b.getName()));
    IO.println("same class: " + (a == b));
 
    Object greeter = a.getDeclaredConstructor().newInstance();
    IO.println("instance of a: " + a.isInstance(greeter));
    IO.println("instance of b: " + b.isInstance(greeter));
    try {
        b.cast(greeter);
    } catch (ClassCastException e) {
        IO.println(e);
    }
}

same name:  true
same class: false
instance of a: true
instance of b: false
java.lang.ClassCastException: Cannot cast Greeter to Greeter

Class.cast gives the short message. when the same mismatch hits a real cast in compiled code (a checkcast instruction), the JVM tells you exactly what happened. this is from a variant of that program where code defined by loader b casts an object from loader a:

java.lang.ClassCastException: class Greeter cannot be cast to class Greeter
  (Greeter is in unnamed module of loader java.net.URLClassLoader @71809907;
   Greeter is in unnamed module of loader java.net.URLClassLoader @158da8e)

when you see the same name on both sides, stop looking at your types and start looking at your loaders. it shows up in app servers that load each webapp with its own loader, in plugin systems, and in dev tools that hot-reload your code with a fresh loader while an old object is still cached somewhere.

the context class loader

delegation only goes up. so what happens when code in a parent loader needs to load a class that only a child can see? java.sql.DriverManager lives in the platform loader, but the JDBC driver it needs to find is in your jar, on the app loader. the platform loader can't see down.

the escape hatch is the thread's context class loader: a loader stashed on every Thread (by default, the app loader) that library code can use explicitly.

ClassLoader tccl = Thread.currentThread().getContextClassLoader();
ServiceLoader<Driver> drivers = ServiceLoader.load(Driver.class, tccl);

ServiceLoader.load(Class) without a loader argument uses the context loader for exactly this reason. app servers and frameworks set it to the right loader before calling into your code. it's a convention, not a rule the JVM enforces, which is why "works in the IDE, fails in the server" bugs often come down to someone forgetting to set it.