Running & troubleshooting
A launcher jar runs like any other executable jar. But because it reconstructs the module graph in process rather than merging everything flat, a few of its behaviours differ from a plain application on a real class path and module path. This chapter shows how to start one, what the single loader means for your code, and the pitfalls worth knowing before you ship.
Running a launcher jar
The jar names the launcher as its Main-Class, so you start it exactly as any executable jar:
java -jar app.jar [args...]
The launcher finds itself, reads its descriptor, META-INF/, rebuilds the loader and module layer, and invokes
your real main class - the sequence covered in How it works. Your arguments pass
straight through to main. Anything the launcher cannot resolve surfaces before main runs, as an exception
with a stack trace and exit code 1 - the same way a bad java -p … -m … command line fails.
What the single loader means for your code
The launcher hosts both the named modules and the class path on one loader, exactly as java -p modulepath -cp classpath does. That fidelity is deliberate, and it carries the JDK's own rules, which
occasionally surprise people coming from a fat jar:
- An automatic module can read the class path; a strict named module cannot. A dependency with a real
module-infosees only what itrequires. If it needs a type that lives on the class path, that read does not exist - just as it would not under a real module path. The fix is not to relax the layer but to give the class-path jar a name: declare a module alias for it, and it joins the module path as an automatic module the strict module canrequires. - A package owned by a module shadows the same package on the class path. When a bundled module and a
class-path jar both contain package
com., the module's classes win and the class-path copy is hidden. Split packages resolve the JDK's way, not first-jar-wins.foo
java -p … -cp … launch does. If your
application relies on a strict module reaching class-path code, or on a split package resolving by class-path
order, it was relying on fat-jar behaviour that a real module path never had.
What the application sees
The application's loader holds only the paths the descriptor names, and it is parented on the platform class
loader. java -jar app. makes the outer jar the system class path, but nothing of that jar's root - the
launcher's classes, the descriptor, the outer manifest - is visible to the application, just as
java -p modulepath -cp classpath shows it nothing but the two paths. An application. the
application carries itself is therefore the one it finds, which is what a framework such as Spring Boot reads
its configuration from; a Spring Boot application runs as a launcher jar as well as from a
bundle.
Two consequences follow from the parent being the platform class loader rather than the system class loader:
- A
ServiceLoaderover the application's loader does not find providers in JDK modules defined to the system class loader, such as the tool modules.java.andutil. spi. ToolProvider. findFirst javax.look those up through the system class loader and still work.tools. ToolProvider - Classes that an external agent appends to the system class path, or that an external
-javaagentjar holds, are not visible to the application.
A launcher jar that is itself a Java agent, declaring no mainClass, keeps the system class loader as the
parent of its loader, because a -javaagent jar's agents share that loader with their host.
Start-up failures
A start-up failure is visible immediately, before your main runs. These are the messages the launcher
itself raises, and what each means:
| Message | Cause and fix |
|---|---|
No 'mainClass' declared in META-INF/ |
The descriptor has no entry point. A build-produced jar always has one; a hand-assembled jar is missing the key. |
Main module not found on the module path: <name> |
mainModule names a module that nothing modulepath names provides, or the jar that provides it derives a different name. |
Two bundled modules resolve to the same name: <name> |
Two jars modulepath names declare or derive the same module name - typically two versions of one library. A module path can carry a name only once; drop one. |
… is aliased as both <a> and <b> |
Two Jenesis-Aliases declarations claim one jar. A jar can carry one module name. |
Module alias <name> is declared for <a> and for <b> |
Bundled modules declare one alias for two different coordinates. An alias can name only one jar. |
Malformed Jenesis-Aliases entry '<entry>' in <jar> |
A bundled jar's manifest carries an alias entry that is not of the form <module>=. |
<key> names <entry>, which this bundle does not hold |
A descriptor key names a jar that jars/ does not hold. A name is refused rather than skipped. |
This bundle holds <n> jars and names none of them: … |
The descriptor names no class path, module path or module layer, so none of the shipped jars would be read. |
The main class <class> declares or inherits no main method … |
The class has no non-private void main(String[]) or void main(), static or not, of its own or inherited. A main that returns a value, or a static main of an interface the class implements, is none either. |
The main class <class> is abstract or an interface but its main method is not static … |
An instance main needs an instance: make the class concrete, or the method static. |
The main class <class> has an instance main method but no non-private constructor without parameters … |
Declare such a constructor, make an inner class static, or make the method static. |
A jar you assemble yourself can also meet these, which a build-produced jar never does:
| Message | Cause and fix |
|---|---|
Malformed access directive … / Malformed addExports/ |
An addExports, addOpens or addReads directive lacks its = or its module/ form. |
Module named by addExports/ |
A grant's source module is not among the bundled modules. |
Layer <layer> holds no module <name> to enable native access for |
enableNativeAccess. or jlayer. names a module the layer does not hold. |
Target module not found: <name> |
A grant's target is neither a bundled nor a boot module, nor ALL-UNNAMED. |
Agent class <name> declares no static premain(String) … |
An agentClass entry names a class without a matching premain or agentmain; the message says when a manifest attribute is missing to capture an Instrumentation. |
Cannot access the main method of <class>, … |
mainClass names a class that is neither on the class path nor in a bundled module, such as a class of the JDK. |
One further failure comes from the JVM rather than the launcher. A bundled module requires a JDK module
that is not resolved by default - jdk., or a module reachable only through qualified exports.
The child layer is bound against the boot layer, and the boot layer contains only what the JVM resolved at
start-up, so the bundled module fails to resolve. Augment the boot layer from the command line:
java --add-modules jdk.incubator.vector -jar app.jar
--add-modules flag at launch is the only way.
Run-time pitfalls
The rest of the launcher's boundaries surface only at run time, and only for applications that do specific things. Most launcher jars never touch them.
Native libraries
A JNI library cannot be loaded straight from a jar, so the launcher extracts a requested library to a temp
file on demand and loads it from there. It finds the library by its platform file name - libfoo. on
Linux for System. - in any folder of a dependency. Two consequences follow:
- The temp file is deleted on a normal exit, but leaks on an abrupt kill (
kill -9, a crash). - A library that finds a sibling library by co-location - rather than through
java.- will not find it, because each library lands in its own temp file. Keep multi-file native bundles self-contained.library. path
When two jars carry the same library, the class-path jars are searched first, in class-path order, then the bundled modules; the first match wins.
"Open my own jar file"
A class the launcher loads has a CodeSource whose location points inside the outer jar (for example
jar:file:/), so Package., sealed packages, and
getProtectionDomain(). all report correctly. Code that opens that location as a URL -
((JarURLConnection) location. - gets the dependency as a jar of its own and can
read its entries. But a dependency is not a standalone jar on disk, so code that turns the location into a file
path and opens that file finds no such file. Code that walks its own jar as a file needs another approach.
Resources in a non-open module package
A resource inside a package of a bundled module stays encapsulated unless that package is opened
unconditionally - by an open module, an automatic module, or an unqualified opens. Only then does
contextClassLoader. find it; a qualified opens does not
widen the flat getResource API. That is exactly how a real java -p … -cp … launch encapsulates it.
. files are always served, as the JDK serves them, and so are resources in no package (top-level
entries, anything under META-INF/) and class-path resources.
Package directories as resources
A class path scan, such as a framework's component scan, starts from getResource("com/ for a package.
The launcher answers it as the JDK does: with a jar: URL where the stored jar has a directory entry for the
package, and with a file: URL for the folder of a launcher jar laid out as an exploded directory. The build
tool keeps the directory entries of every jar it stores in a launcher jar.
A jar built without directory entries answers null for its packages, exactly as the JDK answers for that jar
on any class path, so a scan finds nothing in such a dependency. Class loading and file-resource lookups are
unaffected; only code that starts from a directory URL notices.
The jar stays open
Reading on demand means the outer jar (a ZipFile), plus a cached JarFile once resource URLs are opened,
stays open for the application's lifetime - the trade for never holding the dependencies' bytes in the
heap. Each module layer the application defines from the jar opens it once more, and that handle stays open
too. Under java -jar that is exactly right and needs no action.
It matters only when you embed the launcher in a program of your own. The public entry point is
Launcher., which takes a jar or an exploded directory of the same layout and runs its
main in the current JVM. The loader it builds lives as long as the application it hosts; if you start
several in one process, expect at least one open handle per launch, plus one for each layer it defines.
CodeSource.getCodeSigners reports it, but that attests rather than
re-verifies; see the Reference chapter for the descriptor key.