apache/pulsar · error · IllegalArgumentException

Invalid topic domain: '${value}'

Error message

Invalid topic domain: '${value}'

What it means

TopicDomain.getEnum converts a string ('persistent' or 'non-persistent', case-insensitive) into the TopicDomain enum and throws IllegalArgumentException for any other value. The library restricts topic domains to its known enum values.

Source

Thrown at pulsar-client-admin-api/src/main/java/org/apache/pulsar/common/naming/TopicDomain.java:44

    topic("topic"), segment("segment");

    private String value;

    private TopicDomain(String value) {
        this.value = value;
    }

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

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

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

View on GitHub (pinned to 820761864e)

Solutions

1. Use TopicDomain.persistent.value() (or the enum constant) instead of hand-writing the domain string
2. Validate the domain string against the allowed values before calling getEnum
3. Normalize user input (trim, lowercase) and reject unknown values with a clear message

Example fix

// before
TopicDomain domain = TopicDomain.getEnum(userInput);
// after
if (!"persistent".equalsIgnoreCase(userInput) && !"non-persistent".equalsIgnoreCase(userInput)) {
    throw new IllegalArgumentException("domain must be persistent or non-persistent");
}
TopicDomain domain = TopicDomain.getEnum(userInput.trim());

boolean isValidTopicDomain(String v) {
    return "persistent".equalsIgnoreCase(v) || "non-persistent".equalsIgnoreCase(v);
}

try {
    TopicDomain d = TopicDomain.getEnum(value);
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("topic domain must be persistent|non-persistent: " + value);
}

When it happens

Trigger: Calling TopicDomain.getEnum(value) with anything other than 'persistent' or 'non-persistent' — e.g. building a TopicName from a user-supplied or config-supplied domain string.

Common situations: Typos like 'persistant', using 'persistent://...' parsing with a mangled scheme, dynamic topic URLs from user input containing unexpected domains, or future/unknown domain values from newer clients.

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

• Invalid txnId key:
• Unknown resource type:
• Invalid value %s for the position. Allowed values are [lates
• Invalid string to parse WorkerInfo : ${str}
• --offloadedReadPriority parameter must be one of ${allowed}

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