apache/pulsar · error · org.apache.pulsar.broker.admin.RestException

Label name '%s' is invalid: Pulsar reserves all labels start

Error message

Label name '%s' is invalid: Pulsar reserves all labels starting with 'pulsar_' or 'pulsar.' for internal use

What it means

Pulsar reserves label names using the "pulsar_" or "pulsar." namespaces for its own internal metrics, so user-supplied label names with those suffixes are rejected with HTTP 400 by isValidMetricsName. This avoids ambiguity between user labels and Pulsar's built-in instrumentation.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java:2564

            }
        }
    }

    private static void isValidMetricsName(String labelName) {
        if (labelName == null || labelName.isEmpty()) {
            throw new RestException(Response.Status.BAD_REQUEST, "Label name cannot be null or empty");
        }

        // Prometheus reserves all labels starting with "__" for internal use.
        if (labelName.startsWith("__")) {
            throw new RestException(Response.Status.BAD_REQUEST,
                    String.format("Label name '%s' is invalid: Prometheus reserves all labels starting with '__' "
                            + "for internal use", labelName));
        }

        // Pulsar reserves all labels starting with "pulsar_" or "pulsar." for internal use.
        if (labelName.endsWith("pulsar.") || labelName.endsWith("pulsar_")) {
            throw new RestException(Response.Status.BAD_REQUEST,
                    String.format("Label name '%s' is invalid: Pulsar reserves all labels starting with 'pulsar_' "
                            + "or 'pulsar.' for internal use", labelName));
        }

        // OpenTelemetry reserves all labels starting with "otel_" or "otel." for internal use.
        if (labelName.startsWith("otel.") || labelName.startsWith("otel_")) {
            throw new RestException(Response.Status.BAD_REQUEST,
                    String.format("Label name '%s' is invalid: OpenTelemetry reserves all labels starting with "
                            + "'otel_' or 'otel.' for internal use", labelName));
        }

        boolean matches = METRICS_LABEL_NAME_PATTERN.matcher(labelName).matches();
        if (!matches) {
            throw new RestException(Response.Status.BAD_REQUEST,
                String.format("Label name '%s' is invalid: must match the regex [a-zA-Z_][a-zA-Z0-9_]*", labelName));
        }

    }

View on GitHub (pinned to 820761864e)

Solutions

1. Rename the label so it does not end with "pulsar_" or "pulsar.".
2. Use a different namespace prefix, e.g. "app_" or your organization prefix.
3. Adjust name-generation code to check and reject reserved Pulsar suffixes before sending to the broker.

Example fix

// before
metrics.registerLabel("mypulsar_");

// after
metrics.registerLabel("my_org_label");

if (labelName.endsWith("pulsar_") || labelName.endsWith("pulsar.")) {
    throw new IllegalArgumentException("label name ends with reserved Pulsar namespace: " + labelName);
}

boolean isPulsarSafe(String name) {
    return name != null && !name.endsWith("pulsar_") && !name.endsWith("pulsar.");
}

try {
    metricsApi.registerLabel(labelName);
} catch (RestException e) {
    if (e.getResponse().getStatus() == 400 && (labelName.endsWith("pulsar_") || labelName.endsWith("pulsar."))) {
        log.error("Label '{}' collides with Pulsar reserved namespace", labelName);
    }
}

When it happens

Trigger: Registering a custom metrics label whose name ends with "pulsar." or "pulsar_" (per the validation in PulsarService), e.g. "mypulsar_" or "clusterpulsar.".

Common situations: Naming labels after the product (e.g. "apache_pulsar_") and accidentally hitting the reserved suffix; generated label names that concatenate a suffix ending in pulsar_ or pulsar.; migration from other systems that allowed such names.

Related errors

• Label name '%s' is invalid: Prometheus reserves all labels s
• Label name cannot be null or empty
• Label name '%s' is invalid: OpenTelemetry reserves all label
• Label name '%s' is invalid: must match the regex [a-zA-Z_][a
• Timeout during delete operation

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