{"record":{"id":"c7d018aeb4e31168","repo":"apache/pulsar","slug":"label-name-s-is-invalid-pulsar-reserves-all-la","errorCode":null,"errorMessage":"Label name '%s' is invalid: Pulsar reserves all labels starting with 'pulsar_' or 'pulsar.' for internal use","messagePattern":"Label name '(.+?)' is invalid: Pulsar reserves all labels starting with 'pulsar_' or 'pulsar\\.' for internal use","errorType":"http","errorClass":"org.apache.pulsar.broker.admin.RestException","httpStatus":400,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java","lineNumber":2564,"sourceCode":"            }\n        }\n    }\n\n    private static void isValidMetricsName(String labelName) {\n        if (labelName == null || labelName.isEmpty()) {\n            throw new RestException(Response.Status.BAD_REQUEST, \"Label name cannot be null or empty\");\n        }\n\n        // Prometheus reserves all labels starting with \"__\" for internal use.\n        if (labelName.startsWith(\"__\")) {\n            throw new RestException(Response.Status.BAD_REQUEST,\n                    String.format(\"Label name '%s' is invalid: Prometheus reserves all labels starting with '__' \"\n                            + \"for internal use\", labelName));\n        }\n\n        // Pulsar reserves all labels starting with \"pulsar_\" or \"pulsar.\" for internal use.\n        if (labelName.endsWith(\"pulsar.\") || labelName.endsWith(\"pulsar_\")) {\n            throw new RestException(Response.Status.BAD_REQUEST,\n                    String.format(\"Label name '%s' is invalid: Pulsar reserves all labels starting with 'pulsar_' \"\n                            + \"or 'pulsar.' for internal use\", labelName));\n        }\n\n        // OpenTelemetry reserves all labels starting with \"otel_\" or \"otel.\" for internal use.\n        if (labelName.startsWith(\"otel.\") || labelName.startsWith(\"otel_\")) {\n            throw new RestException(Response.Status.BAD_REQUEST,\n                    String.format(\"Label name '%s' is invalid: OpenTelemetry reserves all labels starting with \"\n                            + \"'otel_' or 'otel.' for internal use\", labelName));\n        }\n\n        boolean matches = METRICS_LABEL_NAME_PATTERN.matcher(labelName).matches();\n        if (!matches) {\n            throw new RestException(Response.Status.BAD_REQUEST,\n                String.format(\"Label name '%s' is invalid: must match the regex [a-zA-Z_][a-zA-Z0-9_]*\", labelName));\n        }\n\n    }","sourceCodeStart":2546,"sourceCodeEnd":2582,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java#L2546-L2582","documentation":"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.","triggerScenarios":"Registering a custom metrics label whose name ends with \"pulsar.\" or \"pulsar_\" (per the validation in PulsarService), e.g. \"mypulsar_\" or \"clusterpulsar.\".","commonSituations":"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.","solutions":["Rename the label so it does not end with \"pulsar_\" or \"pulsar.\".","Use a different namespace prefix, e.g. \"app_\" or your organization prefix.","Adjust name-generation code to check and reject reserved Pulsar suffixes before sending to the broker."],"exampleFix":"// before\nmetrics.registerLabel(\"mypulsar_\");\n\n// after\nmetrics.registerLabel(\"my_org_label\");","handlingStrategy":"validation","validationCode":"if (labelName.endsWith(\"pulsar_\") || labelName.endsWith(\"pulsar.\")) {\n    throw new IllegalArgumentException(\"label name ends with reserved Pulsar namespace: \" + labelName);\n}","typeGuard":"boolean isPulsarSafe(String name) {\n    return name != null && !name.endsWith(\"pulsar_\") && !name.endsWith(\"pulsar.\");\n}","tryCatchPattern":"try {\n    metricsApi.registerLabel(labelName);\n} catch (RestException e) {\n    if (e.getResponse().getStatus() == 400 && (labelName.endsWith(\"pulsar_\") || labelName.endsWith(\"pulsar.\"))) {\n        log.error(\"Label '{}' collides with Pulsar reserved namespace\", labelName);\n    }\n}","preventionTips":["Avoid naming labels with pulsar_ or pulsar. suffixes/prefixes","Use your organization or app prefix for custom labels","Sanitize generated names against reserved Pulsar namespaces"],"tags":["metrics","prometheus","validation","reserved-prefix"],"backgroundTag":"metrics-label-name-invalid","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}