apache/iceberg · error · IllegalStateException

Cannot build StorageCredential, some of required attributes…

Error message

Cannot build StorageCredential, some of required attributes are not set: prefix

What it means

StorageCredential is an immutable value object generated with a required 'prefix' attribute (the storage location URI the credential applies to). The Builder refuses to produce an instance when prefix was never set, throwing IllegalStateException listing the missing attribute. This is a fail-fast guard so consumers never receive a credential with no scope.

Solutions

1. Set prefix on the builder before build(): new StorageCredential.Builder().prefix(locationUri)...
2. If the credential came from a remote response, validate the response contains a prefix before mapping it into the builder
3. Ensure the catalog server (or test mock) returns the prefix field in its storage credential JSON

Example fix

// before
StorageCredential cred = new StorageCredential.Builder()
    .config(config)
    .build(); // IllegalStateException: prefix not set
// after
StorageCredential cred = new StorageCredential.Builder()
    .prefix("s3://bucket/path/")
    .config(config)
    .build();

if (prefix == null || prefix.isEmpty()) {
  throw new IllegalArgumentException("Storage credential prefix is required");
}
StorageCredential cred = new StorageCredential.Builder().prefix(prefix).config(config).build();

try {
  return new StorageCredential.Builder().prefix(p).config(cfg).build();
} catch (IllegalStateException e) {
  log.error("Credential build failed: {}", e.getMessage());
  throw e;
}

When it happens

Trigger: Calling StorageCredential.Builder.build() without first invoking .prefix(...), e.g. constructing a credential from a REST catalog response that lacked a storage-credentials prefix, or hand-building a credential and forgetting the prefix field.

Common situations: Deserializing vended credentials from a REST catalog where the server omitted 'prefix'; custom catalog code vendoring credentials without setting the location; tests/fixtures constructing credentials with only config map.

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

• Received a malformed path for a REST request
• Can't index multiple DVs for
• Cannot add fields to map keys:
• Cannot alter map keys:
• Cannot assume role to sign REST requests because is not…

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/f356545be1df23f7. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/io/ImmutableStorageCredential.java:293

      for (Map.Entry<String, ? extends String> e : entries.entrySet()) {
        String k = e.getKey();
        String v = e.getValue();
        this.config.put(
            Objects.requireNonNull(k, "config key"),
            Objects.requireNonNull(v, v == null ? "config value for key: " + k : null));
      }
      return this;
    }

    /**
     * Builds a new {@link ImmutableStorageCredential ImmutableStorageCredential}.
     *
     * @return An immutable instance of StorageCredential
     * @throws java.lang.IllegalStateException if any required attributes are missing
     */
    public ImmutableStorageCredential build() {
      if (null == prefix) {
        throw new IllegalStateException(
            "Cannot build StorageCredential, some of required attributes are not set: prefix");
      }

      return ImmutableStorageCredential.validate(
          new ImmutableStorageCredential(prefix, createSerializableMap(false, false, config)));
    }
  }

  private static <K, V> Map<K, V> createSerializableMap(
      boolean checkNulls, boolean skipNulls, Map<? extends K, ? extends V> map) {
    Map<K, V> linkedMap = new LinkedHashMap<>();
    if (skipNulls || checkNulls) {
      for (Map.Entry<? extends K, ? extends V> e : map.entrySet()) {
        K k = e.getKey();
        V v = e.getValue();
        if (skipNulls) {
          if (k == null || v == null) continue;
        } else if (checkNulls) {

View on GitHub (pinned to 86d9c8fc54)