GoogleContainerTools/jib · error · IllegalArgumentException

Image name must be set when building a TarImage; use TarImag

Error message

Image name must be set when building a TarImage; use TarImage#named(...) to set the name of the target image

What it means

Containerizer.to(TarImage) builds an OCI/Docker tarball that must be tagged with an image name. If TarImage#named(...) was never called, the optional ImageReference is empty and this IllegalArgumentException is thrown because a tar image cannot be built namelessly.

Source

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

        DockerClientResolver.resolve(dockerDaemonImage.getDockerEnvironment())
            .orElse(
                new CliDockerClient(
                    dockerDaemonImage.getDockerExecutable(),
                    dockerDaemonImage.getDockerEnvironment()));

    return to(dockerClient, dockerDaemonImage);
  }

  /**
   * Gets a new {@link Containerizer} that containerizes to a tarball archive.
   *
   * @param tarImage the {@link TarImage} that defines target output file
   * @return a new {@link Containerizer}
   */
  public static Containerizer to(TarImage tarImage) {
    Optional<ImageReference> imageReference = tarImage.getImageReference();
    if (!imageReference.isPresent()) {
      throw new IllegalArgumentException(
          "Image name must be set when building a TarImage; use TarImage#named(...) to set the name"
              + " of the target image");
    }

    ImageConfiguration imageConfiguration =
        ImageConfiguration.builder(imageReference.get()).build();

    Function<BuildContext, StepsRunner> stepsRunnerFactory =
        buildContext -> StepsRunner.begin(buildContext).tarBuildSteps(tarImage.getPath());

    return new Containerizer(
        DESCRIPTION_FOR_TARBALL, imageConfiguration, stepsRunnerFactory, false);
  }

  /**
   * Gets a new {@link Containerizer} that containerizes to a Docker daemon.
   *
   * @param dockerClient the {@link DockerClient} to connect

View on GitHub (pinned to fb949e2676)

Solutions

Call TarImage#named(...) with a valid image reference before passing to Containerizer.to
Ensure the ImageReference is set (e.g. TarImage.at(Paths.get("out.tar")).named("my/repo:tag"))
Validate the reference format if named() was called but with an invalid string that didn't populate the reference

Example fix

// before
TarImage tarImage = TarImage.at(Paths.get("image.tar"));
Containerizer.to(tarImage);
// after
Containerizer.to(TarImage.at(Paths.get("image.tar")).named("my-app:latest"));

Defensive patterns

Strategy: type-guard

Validate before calling

if (!tarImage.getImageReference().isPresent()) { throw new IllegalStateException("Call TarImage#named before building"); }

Type guard

boolean isNamedTarImage(TarImage t) { return t.getImageReference().isPresent(); }

Try / catch

try { containerizer.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("TarImage#named")) { /* rebuild containerizer with named image */ } }

Prevention

Always chain .named(...) on TarImage.at(...)
Centralize TarImage construction in a helper that enforces naming
Unit-test containerizer configuration before builds

When it happens

Trigger: Calling Containerizer.to(TarImage.at(path)) without chaining TarImage#named("ref"), then building.

Common situations: Migrating code from registry builds to tar outputs; copying examples that omit .named(); constructing TarImage programmatically and forgetting the name step.

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

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