GoogleContainerTools/jib · error · IllegalStateException

<field> is required but not set

Error message

<field> is required but not set

What it means

BuildContext.Builder.build() collects builder fields that were not set into a missingFields list and throws IllegalStateException naming them — one field: "<field> is required but not set". This is Jib's internal guard that a fully-specified build configuration (target image, credentials, etc.) exists before the build runs.

Source

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

              targetFormat,
              offline,
              layerConfigurations,
              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() {

View on GitHub (pinned to fb949e2676)

Solutions

1. Set the field named in the message on the BuildContext.Builder (e.g. .setTargetImage(...)) before calling build()
2. In Maven/Gradle, configure the missing jib parameter (commonly to.image)
3. Check the ordering: setters called after build() do not apply
4. If using plugin extensions/profiles, ensure the active profile defines the required jib values

Example fix

// before
BuildContext builder = ...; // setTargetImage never called
BuildContext context = builder.build();
// after
builder.setTargetImage(RegistryImage.named("gcr.io/project/app"));
BuildContext context = builder.build();

List<String> missing = new ArrayList<>();
if (targetImage == null) missing.add("target image");
if (credentialRetrievers.isEmpty()) missing.add("credential retrievers");
if (!missing.isEmpty()) throw new IllegalStateException(missing + " must be set before build()");

static <T> T requireSet(T v, String name) {
  if (v == null) throw new IllegalStateException(name + " is required but not set");
  return v;
}

try {
  BuildContext ctx = builder.build();
} catch (IllegalStateException e) {
  if (e.getMessage().endsWith("is required but not set")) {
    throw new ConfigurationException("Jib misconfiguration: " + e.getMessage());
  }
  throw e;
}

When it happens

Trigger: BuildContext.build() is invoked with exactly one unset required builder field (missingFields.size() == 1) — e.g. target image, credential retrievers, or container configuration omitted from the Jib extension/plugin or the Jib Core API builder.

Common situations: Programmatic Jib Core/Lib usage where a builder field was forgotten; Maven/Gradle plugin misconfiguration where <to><image> or auth is absent; missing settings causing downstream nulls.

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> and <field2> are required but not set
• <field1>, <field2>, ... and <fieldN> are required but not se
• property + " must be an integer: " + value
• property + " cannot be less than " + validRange.lowerEndpoin
• property + " cannot be greater than " + validRange.upperEndp

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