apache/pulsar · error · IllegalArgumentException

Invalid package domain: '${value}'

Error message

Invalid package domain: '${value}'

What it means

PackageType.getEnum converts a string (e.g. from a package URL like 'function://') into a PackageType enum by case-insensitive match against known values. If no enum constant matches, it throws IllegalArgumentException naming the unrecognized domain. Pulsar packages are identified by a domain prefix, so an unknown prefix means the package URL is malformed or from a newer/older Pulsar version.

Source

Thrown at pulsar-client-admin-api/src/main/java/org/apache/pulsar/packages/management/core/common/PackageType.java:43

    FUNCTION("function"), SINK("sink"), SOURCE("source");

    private final String value;

    PackageType(String value) {
        this.value = value;
    }

    public String value() {
        return this.value;
    }

    public static PackageType getEnum(String value) {
        for (PackageType e : values()) {
            if (e.value.equalsIgnoreCase(value)) {
                return e;
            }
        }
        throw new IllegalArgumentException("Invalid package domain: '" + value + "'");
    }

    @Override
    public String toString() {
        return this.value;
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the package URL domain prefix to one of the supported values (function, sink, source, package).
2. Check the string for typos, extra whitespace, or missing '://' prefix before calling getEnum.
3. Upgrade client/broker so both sides know the same PackageType values.
4. Catch IllegalArgumentException around getEnum and validate the domain before use.

Example fix

// before
PackageType type = PackageType.getEnum("functions");
// after
PackageType type = PackageType.getEnum("function");

boolean valid = Arrays.stream(PackageType.values())
    .anyMatch(t -> t.toString().equalsIgnoreCase(value));
if (!valid) {
    throw new IllegalArgumentException("Unknown package domain: " + value);
}

try {
    PackageType type = PackageType.getEnum(value);
} catch (IllegalArgumentException e) {
    log.error("Unsupported package type in URL: {}", value);
    return;
}

When it happens

Trigger: Calling PackageType.getEnum(value) with a string that is not one of the defined package types (function, sink, source, package), e.g. parsing a package name whose URL prefix is 'foo://', empty, or misspelled ('Function' is OK, 'fn://' is not).

Common situations: Typo in a packages:// or function:// URL passed to the Packages admin API; using a package domain introduced in a newer Pulsar version against an older broker/client; hand-constructed package names missing the 'domain://' prefix.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• entryFilterNames can't be empty. To remove entry filters use
• The offloadPolicies must be specified for namespace offload.
• The bucket must be specified for namespace offload.
• cluster data is required
• Can not enable for all producers but denies for replicators,

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/97d5d11b853bb0eb. Report an issue: GitHub.