GoogleContainerTools/jib · error · CommandLine.ParameterException

Missing option: --name must be specified when using --target

Error message

Missing option: --name must be specified when using --target=tar://....

What it means

Jib CLI validates CommonCliOptions in validate(): building to a tar file via --target=tar://... requires the image's logical name, supplied through --name, because a tar archive has no registry to imply one. If the target starts with 'tar://' and --name is absent, a CommandLine.ParameterException is thrown before the build starts.

Source

Thrown at jib-cli/src/main/java/com/google/cloud/tools/jib/cli/CommonCliOptions.java:424

  }

  public List<String> getAdditionalTags() {
    return additionalTags;
  }

  /**
   * Returns the full path to the image metadata json file, if provided.
   *
   * @return optional value of path to image json file
   */
  public Optional<Path> getImageJsonPath() {
    return Optional.ofNullable(imageJsonPath);
  }

  /** Validates parameters defined in this class that could not be done declaratively. */
  public void validate() {
    if (targetImage.startsWith(TAR_IMAGE_PREFIX) && name == null) {
      throw new CommandLine.ParameterException(
          spec.commandLine(),
          "Missing option: --name must be specified when using --target=tar://....");
    }
  }
}

View on GitHub (pinned to fb949e2676)

Solutions

1. Add --name (e.g. --name=my-image:tag) alongside --target=tar://....
2. Update build scripts/aliases to include --name whenever the target is a tar path.
3. Use a registry or daemon target instead if a name is not meaningful for your workflow.

Example fix

// before
jib build --target=tar://out/app.tar
// after
jib build --target=tar://out/app.tar --name=my-app:1.0

if (target.startsWith("tar://") && !args.contains("--name")) {
  throw new IllegalArgumentException("--name is required when --target=tar://...");
}

When it happens

Trigger: Running jib build with --target=tar:///path/to/image.tar and no --name flag, or with --name omitted in a script/alias that only sets target.

Common situations: Scripting tar builds for offline distribution, migrating commands from registry-target builds to tar builds and forgetting the extra required flag.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• The class file (${jarEntry}) is of an invalid format.
• Reached end of class file (${jarEntry}) before being able to
• ${fieldName} must be a number of milliseconds since epoch or
• octalPermissions must be a 3-digit octal number (000-777)
• The input JAR (${jarPath}) is compiled with Java ${jarJavaVe

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