gradle/gradle · error · ManifestException

The Key=%s violates the Manifest spec!

Error message

The Key=%s violates the Manifest spec!

What it means

DefaultAttributes.put validates the key by constructing java.util.jar.Attributes.Name(key). The JDK accepts only names that start with a letter, contain solely alphanumerics and '_', '-', '.', '*', and are at most 70 bytes long. Keys breaking these rules raise ManifestException with 'The Key=%s violates the Manifest spec!'.

Source

Thrown at platforms/jvm/platform-jvm/src/main/java/org/gradle/api/java/archives/internal/DefaultAttributes.java:65

    }

    @Override
    public Object get(Object key) {
        return attributes.get(key);
    }

    @Override
    public Object put(String key, Object value) {
        if (key == null) {
            throw new ManifestException("The key of a manifest attribute must not be null.");
        }
        if (value == null) {
            throw new ManifestException(String.format("The value of a manifest attribute must not be null (Key=%s).", key));
        }
        try {
            new java.util.jar.Attributes.Name(key);
        } catch (IllegalArgumentException e) {
            throw new ManifestException(String.format("The Key=%s violates the Manifest spec!", key));
        }
        return attributes.put(key, value);
    }

    @Override
    public Object remove(Object key) {
        return attributes.remove(key);
    }

    @Override
    public void putAll(Map<? extends String, ? extends Object> m) {
        for (Entry<? extends String, ? extends Object> entry : m.entrySet()) {
            put(entry.getKey(), entry.getValue());
        }
    }

    @Override
    public void clear() {

View on GitHub (pinned to 534f27719b)

Solutions

  1. Rewrite the key using only letters, digits, '_', '-', '.', '*' — e.g. 'My-Attribute' instead of 'My Attribute'.
  2. Shorten generated keys to at most 70 bytes.
  3. Start keys with a letter, never a digit or symbol.
  4. Validate keys yourself with new Attributes.Name(key) before passing them to attributes().

Example fix

// before
manifest.attributes(['My Cool Feature': 'enabled'])  // space is illegal

// after
manifest.attributes(['My-Cool-Feature': 'enabled'])
Defensive patterns

Strategy: validation

Validate before calling

boolean isValidHeaderName(String name) {
    try {
        new java.util.jar.Attributes.Name(name)
        return true
    } catch (IllegalArgumentException ignored) {
        return false
    }
}
def safe = attrs.findAll { k, v -> isValidHeaderName(k as String) }
manifest.attributes(safe)

Try / catch

try {
    new java.util.jar.Attributes.Name(key)
    manifest.attributes([(key): value])
} catch (IllegalArgumentException | org.gradle.api.java.archives.ManifestException e) {
    throw new GradleException("Invalid manifest header name '${key}': ${e.message}", e)
}

Prevention

When it happens

Trigger: attributes.put('Bundle Name', 'x') (space), 'My:Key' (colon), a key starting with a digit or symbol, non-ASCII characters, or a machine-generated key longer than 70 bytes.

Common situations: Multi-word keys copied from docs that use spaces instead of hyphens; generated keys (package name + suffix) exceeding the 70-byte limit; localized or unicode attribute names.

Related errors

AI-assisted analysis of gradle/gradle@534f27719b (2026-08-22). Data as JSON: /api/errors/18b7ca025b58c4fb. Report an issue: GitHub.