GoogleContainerTools/jib · error · IllegalStateException

<field1> and <field2> are required but not set

Error message

<field1> and <field2> are required but not set

What it means

BuildContext.Builder.build() validates that required fields (base image, target image, etc.) were set before constructing the BuildConfiguration. When exactly one or two required fields are missing, it throws an IllegalStateException naming them. Jib throws this because a build context without these fields cannot produce a valid build plan.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/configuration/BuildContext.java:352

              toolName,
              toolVersion,
              eventHandlers,
              // TODO: try setting global User-Agent: here
              new FailoverHttpClient(
                  allowInsecureRegistries,
                  JibSystemProperties.sendCredentialsOverHttp(),
                  eventHandlers::dispatch),
              executorService == null ? Executors.newCachedThreadPool() : executorService,
              executorService == null, // shutDownExecutorService
              alwaysCacheBaseImage,
              registryMirrors,
              enablePlatformTags);

        case 1:
          throw new IllegalStateException(missingFields.get(0) + " is required but not set");

        case 2:
          throw new IllegalStateException(
              missingFields.get(0) + " and " + missingFields.get(1) + " are required but not set");

        default:
          missingFields.add("and " + missingFields.remove(missingFields.size() - 1));
          StringJoiner errorMessage = new StringJoiner(", ", "", " are required but not set");
          for (String missingField : missingFields) {
            errorMessage.add(missingField);
          }
          throw new IllegalStateException(errorMessage.toString());
      }
    }

    @Nullable
    @VisibleForTesting
    Path getBaseImageLayersCacheDirectory() {
      return baseImageLayersCacheDirectory;
    }

View on GitHub (pinned to fb949e2676)

Solutions

1. Read the exception message and call the corresponding setter(s) on the BuildContext.Builder (e.g. builder.setBaseImage(...), builder.setTargetImage(...)) before calling build()
2. If building from config, log/inspect which fields your config loader populated and fix the missing one
3. Wrap builder construction in a helper that validates all required inputs before calling build()

Example fix

// before
BuildContext.Builder builder = BuildContext.builder()
    .setBaseImageRegistry("gcr.io")
    .setTargetImage(...);
BuildContext ctx = builder.build(); // throws
// after
BuildContext.Builder builder = BuildContext.builder()
    .setBaseImageRegistry("gcr.io")
    .setBaseImage(...)              // add the missing required setter
    .setTargetImage(...);
BuildContext ctx = builder.build();

// Java
List<String> missing = new ArrayList<>();
if (baseImage == null) missing.add("base image");
if (targetImage == null) missing.add("target image");
if (!missing.isEmpty()) throw new IllegalArgumentException("Missing: " + missing);
BuildContext ctx = builder.build();

When it happens

Trigger: Calling build() on a BuildContext.Builder after setting only some required fields — e.g. a builder where setBaseImage was called but setTargetImage (or another mandatory field) was not, leaving 1-2 entries in the missingFields list.

Common situations: Programmatic use of jib-core without the Maven/Gradle plugins: forgetting to call one setter on the builder, constructing a builder from partially parsed configuration, or refactoring code that dropped a setter call.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• <field1>, <field2>, ... and <fieldN> are required but not se
• Failed to construct entrypoint on JavaContainerBuilder; jvmF
• Failed to construct entrypoint because no files were added t
• <field> is required but not set
• container.appRoot is not an absolute Unix-style path: ${inva

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