apache/iceberg · error · IllegalArgumentException

Header name cannot be empty

Error message

Header name cannot be empty

What it means

HTTPHeader is an Immutables value type whose @Value.Check rejects headers with an empty name at construction time. Creating an HTTPHeader with name "" throws IllegalArgumentException immediately, before any HTTP request is made. This is a fail-fast invariant protecting against malformed HTTP headers.

Solutions

1. Fix the code/config that produced the empty header name before constructing HTTPHeader.
2. Filter or skip entries with blank names when building the header map programmatically.
3. Validate user-supplied header strings (split on ':' and trim, then reject empty names) before conversion.

Example fix

// before
HTTPHeaders.from(Maps.filterValues(raw, v -> v != null)); // may contain "" key
// after
Map<String, String> clean = raw.entrySet().stream()
    .filter(e -> !e.getKey().isEmpty())
    .collect(ImmutableMap.toImmutableMap(Map.Entry::getKey, Map.Entry::getValue));

if (name == null || name.isEmpty()) {
  throw new IllegalArgumentException("Header name must be non-empty");
}
HTTPHeader header = HTTPHeader.of(name, value);

When it happens

Trigger: Calling HTTPHeader.of("", value), ImmutableHTTPHeader.builder().name("")...build(), or programmatically building headers from a map/collection that contains an empty key (e.g. splitting a "Name: Value" string that produced an empty name).

Common situations: Parsing auth headers from config lines with a stray delimiter; building headers from a properties map where a key was accidentally blank; off-by-one substring when extracting a header name.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 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 build StorageCredential, some of required attributes…

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/HTTPHeaders.java:118

                .collect(Collectors.toList()))
        .build();
  }

  /** Represents an HTTP header as a name-value pair. */
  @Value.Style(redactedMask = "****", depluralize = true)
  @Value.Immutable
  @SuppressWarnings({"ImmutablesStyle", "SafeLoggingPropagation"})
  interface HTTPHeader {

    String name();

    @Value.Redacted
    String value();

    @Value.Check
    default void check() {
      if (name().isEmpty()) {
        throw new IllegalArgumentException("Header name cannot be empty");
      }
    }

    static HTTPHeader of(String name, String value) {
      return ImmutableHTTPHeader.builder().name(name).value(value).build();
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)