What causes "attributes cannot have a NULL key" in apache/hadoop?

Sanitize before calling: drop or reject entries whose key is null or empty

apache/hadoop · error · IllegalArgumentException

attributes cannot have a NULL key

Error message

attributes cannot have a NULL key

What it means

KeyProvider.Options.setAttributes copies the caller's attribute map into the options; java.util.HashMap tolerates a null key, but the serialized Metadata format written into the keystore cannot represent one, so a null key is rejected up front with IllegalArgumentException instead of corrupting the store later.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/crypto/key/KeyProvider.java:362

    public Options setCipher(String cipher) {
      this.cipher = cipher;
      return this;
    }

    public Options setBitLength(int bitLength) {
      this.bitLength = bitLength;
      return this;
    }

    public Options setDescription(String description) {
      this.description = description;
      return this;
    }

    public Options setAttributes(Map<String, String> attributes) {
      if (attributes != null) {
        if (attributes.containsKey(null)) {
          throw new IllegalArgumentException("attributes cannot have a NULL key");
        }
        this.attributes = new HashMap<String, String>(attributes);
      }
      return this;
    }

    public String getCipher() {
      return cipher;
    }

    public int getBitLength() {
      return bitLength;
    }

    public String getDescription() {
      return description;
    }

View on GitHub (pinned to 2add963021)

Solutions

Sanitize before calling: drop or reject entries whose key is null or empty
Validate at parse time: every attribute token must contain '=' with a non-empty left-hand side
Use Objects.requireNonNull(key) while building the map to fail at the true source

Example fix

// before
Map<String,String> attrs = new HashMap<>();
attrs.put(null, "v"); // slips through HashMap
options.setAttributes(attrs);

// after
Map<String,String> attrs = new HashMap<>();
attrs.put("purpose", "v");
options.setAttributes(attrs);

Defensive patterns

Strategy: validation

Validate before calling

Map<String,String> safe = new LinkedHashMap<>();
for (Map.Entry<String,String> e : rawAttributes.entrySet()) {
  if (e.getKey() == null || e.getKey().isEmpty()) continue; // or throw
  safe.put(e.getKey(), e.getValue());
}
options.setAttributes(safe);

Type guard

static boolean hasNoNullKeys(Map<String,String> attrs) {
  return attrs == null || !attrs.containsKey(null);
}

Try / catch

catch (IllegalArgumentException e) { if ("attributes cannot have a NULL key".equals(e.getMessage())) { // fix the attribute map at its source (parser) and rebuild options } else { throw e; } }

Prevention

Validate attribute tokens when parsing key=value strings: require non-empty key before '='
Never use null as a map key sentinel
Build attribute maps with Objects.requireNonNull on each key

When it happens

Trigger: Building the attributes map from parsed key=value strings where an empty left-hand side becomes null; map.put(null, value) from unvalidated input; wrappers that insert a null key as a sentinel.

Common situations: Parsing user-supplied attributes (e.g. `hadoop key create -attribute` style input) by splitting on '=' without checking for an empty key side; config-driven attribute maps.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/bb0b1853aa76a928. Report an issue: GitHub.