GoogleContainerTools/jib · error · IllegalStateException

Failed to construct entrypoint on JavaContainerBuilder; jvmF

Error message

Failed to construct entrypoint on JavaContainerBuilder; jvmFlags were set, but mainClass is null. Specify the main class using JavaContainerBuilder#setMainClass(String), or consider using MainClassFinder to infer the main class.

What it means

JavaContainerBuilder.toContainerBuilder requires a mainClass to construct the container entrypoint. If jvmFlags were set but no main class was configured, it throws IllegalStateException — a java invocation with flags but no main class would be broken, so jib refuses to build. This is a configuration-consistency check, not an I/O failure.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/api/JavaContainerBuilder.java:547

   * @return this
   */
  public JavaContainerBuilder setModificationTimeProvider(
      ModificationTimeProvider modificationTimeProvider) {
    this.modificationTimeProvider = modificationTimeProvider;
    return this;
  }

  /**
   * Returns a new {@link JibContainerBuilder} using the parameters specified on the {@link
   * JavaContainerBuilder}.
   *
   * @return a new {@link JibContainerBuilder} using the parameters specified on the {@link
   *     JavaContainerBuilder}
   * @throws IOException if building the {@link JibContainerBuilder} fails.
   */
  public JibContainerBuilder toContainerBuilder() throws IOException {
    if (mainClass == null && !jvmFlags.isEmpty()) {
      throw new IllegalStateException(
          "Failed to construct entrypoint on JavaContainerBuilder; "
              + "jvmFlags were set, but mainClass is null. Specify the main class using "
              + "JavaContainerBuilder#setMainClass(String), or consider using MainClassFinder to "
              + "infer the main class.");
    }
    if (classpathOrder.isEmpty()) {
      throw new IllegalStateException(
          "Failed to construct entrypoint because no files were added to the JavaContainerBuilder");
    }

    Map<LayerType, FileEntriesLayer.Builder> layerBuilders = new EnumMap<>(LayerType.class);

    // Add classes to layer configuration
    for (PathPredicatePair directory : addedClasses) {
      addDirectoryContentsToLayer(
          layerBuilders,
          LayerType.CLASSES,
          directory.path,

View on GitHub (pinned to fb949e2676)

Solutions

1. Call JavaContainerBuilder#setMainClass("com.example.Main") before toContainerBuilder
2. Use MainClassFinder to infer the main class from compiled classes and pass it via setMainClass
3. If jvmFlags aren't needed, either set mainClass anyway or remove the flags so this check doesn't trip
4. Catch IllegalStateException and prompt for the missing main class in tooling

Example fix

// before
builder.setJvmFlags("-Xms512m");
JibContainerBuilder b = builder.toContainerBuilder();
// after
builder.setJvmFlags("-Xms512m").setMainClass("com.example.Main");
JibContainerBuilder b = builder.toContainerBuilder();

if (mainClass == null) builder.setMainClass(MainClassFinder.findMainClass(Paths.get("target/classes")).orElse("com.example.Main"));

try { JibContainerBuilder b = builder.toContainerBuilder(); } catch (IllegalStateException e) { if (e.getMessage().contains("mainClass")) builder.setMainClass(fallbackMainClass); }

When it happens

Trigger: Calling setJvmFlags(...) without ever calling setMainClass(...), then toContainerBuilder() (also reachable via createJibContainerBuilder and fromExplodedWar paths).

Common situations: Refactored builder code where setMainClass was dropped; relying on MainClassFinder output that was never wired in; building libraries where the main class is discovered only later.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• `Main-Class:` attribute for an application main class not de
• `Main-Class:` attribute for an application main class not de
• Computing the entrypoint is currently not supported.
• Failed to construct entrypoint because no files were added t
• <field1> and <field2> are required but not set

AI-assisted analysis of GoogleContainerTools/jib@fb949e2676 (2026-09-06). Data as JSON: /api/errors/6ac86ce95663e611. Report an issue: GitHub.