apache/pulsar · error · IllegalArgumentException

rack name is invalid, it should not be null, empty or '/'

Error message

rack name is invalid, it should not be null, empty or '/'

What it means

BookieInfoImpl.Builder.checkArgument throws IllegalArgumentException when the rack name is null, empty, or '/'. Bookie rack names used for placement awareness must be a non-empty string identifying a rack, and '/' is rejected as invalid.

Source

Thrown at pulsar-client-admin-api/src/main/java/org/apache/pulsar/common/policies/data/impl/BookieInfoImpl.java:64

        public BookieInfoImplBuilder rack(String rack) {
            this.rack = rack;
            return this;
        }

        public BookieInfoImplBuilder hostname(String hostname) {
            this.hostname = hostname;
            return this;
        }

        public BookieInfoImpl build() {
            checkArgument(rack != null && !rack.isEmpty() && !rack.equals(PATH_SEPARATOR),
                    "rack name is invalid, it should not be null, empty or '/'");
            return new BookieInfoImpl(rack, hostname);
        }

        public static void checkArgument(boolean expression, @NonNull Object errorMessage) {
            if (!expression) {
                throw new IllegalArgumentException(String.valueOf(errorMessage));
            }
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Provide a concrete rack name like "/dc1/rack0" path-style identifier (non-empty, not just "/") per your placement policy
2. Validate the rack string before building: rack != null && !rack.isEmpty() && !rack.equals("/")
3. Fix the source config/env var that supplies the rack value

Example fix

// before
String rack = System.getenv("BOOKIE_RACK"); // may be "/" or empty
BookieInfoImpl info = BookieInfoImpl.builder().rack(rack).hostname(host).build();
// after
String rack = System.getenv("BOOKIE_RACK");
if (rack == null || rack.isEmpty() || "/".equals(rack)) {
    rack = "/default-rack";
}
BookieInfoImpl info = BookieInfoImpl.builder().rack(rack).hostname(host).build();

boolean isValidRack(String rack) {
    return rack != null && !rack.isEmpty() && !"/".equals(rack);
}

try {
    BookieInfoImpl info = BookieInfoImpl.builder().rack(rack).hostname(host).build();
} catch (IllegalArgumentException e) {
    logger.error("Invalid rack '{}': must be non-null, non-empty, and not '/'", rack);
}

When it happens

Trigger: Calling bookieInfo build()/setBookieInfo with rack = null, "", or "/" — e.g. parsing a rack string from an environment variable or config file that is unset or contains just a slash.

Common situations: Empty RACK env/config in deployment scripts, yaml config with rack: / placeholder, script defaulting rack to '/' thinking it means root, or hostname/rack splitting logic producing empty strings.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• failoverThreshold must be larger than 0
• recoverThreshold must be larger than 0
• checkHealthyIntervalMs must be larger than 0
• testTopic can not be blank
• pulsarServiceUrlArray can not be empty

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