{"record":{"id":"f74884e339862f77","repo":"apache/pulsar","slug":"need-to-provide-a-persistent-topic-name-f74884","errorCode":null,"errorMessage":"Need to provide a persistent topic name","messagePattern":"Need to provide a persistent topic name","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CliCommand.java","lineNumber":56,"sourceCode":"import picocli.CommandLine.Model.CommandSpec;\nimport picocli.CommandLine.Spec;\n\npublic abstract class CliCommand implements Callable<Integer> {\n    @Spec\n    private CommandSpec commandSpec;\n\n    static String validateNamespace(String namespace) {\n        return NamespaceName.get(namespace).toString();\n    }\n\n    static String validateTopicName(String topic) {\n        return TopicName.get(topic).toString();\n    }\n\n    static String validatePersistentTopic(String topic) {\n        TopicName topicName = TopicName.get(topic);\n        if (topicName.getDomain() != TopicDomain.persistent) {\n            throw new IllegalArgumentException(\"Need to provide a persistent topic name\");\n        }\n        return topicName.toString();\n    }\n\n    static String validateNonPersistentTopic(String topic) {\n        TopicName topicName = TopicName.get(topic);\n        if (topicName.getDomain() != TopicDomain.non_persistent) {\n            throw new IllegalArgumentException(\"Need to provide a non-persistent topic name\");\n        }\n        return topicName.toString();\n    }\n\n    static MessageId validateMessageIdString(String resetMessageIdStr) throws PulsarAdminException {\n        return validateMessageIdString(resetMessageIdStr, -1);\n    }\n\n    static MessageId validateMessageIdString(String resetMessageIdStr, int partitionIndex) throws PulsarAdminException {\n        String[] messageId = resetMessageIdStr.split(\":\");","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CliCommand.java#L38-L74","documentation":"The pulsar-admin CLI command validates that the topic argument parses to a topic whose domain is persistent (persistent://tenant/namespace/topic). If the supplied topic is non-persistent (or lacks a domain so it cannot be confirmed persistent), CliCommand.validatePersistentTopic throws IllegalArgumentException before the admin operation runs.","triggerScenarios":"Running a persistent-topic-only admin command (e.g. certain lookups, stats, or subscriptions commands) with a topic URL of the form non-persistent://tenant/namespace/topic, or a bare short name that resolves to a non-persistent default domain.","commonSituations":"Copy-pasting a topic name from a non-persistent producer config; omitting the persistent:// prefix and relying on a broker configuration whose default domain is non-persistent; scripting admin commands against a mix of persistent and non-persistent topics.","solutions":["Use the full persistent topic URL: persistent://tenant/namespace/topic","If the topic really is non-persistent, use the corresponding non-persistent admin command/endpoint instead","Check your broker's default topic domain configuration if you are relying on short topic names","Echo/validate the topic argument in your script before invoking the CLI"],"exampleFix":"// before\npulsar-admin topics stats non-persistent://public/default/my-topic\n// after\npulsar-admin topics stats persistent://public/default/my-topic","handlingStrategy":"validation","validationCode":"// Validate topic domain before invoking the CLI/admin command\nif (!topic.startsWith(\"persistent://\")) {\n    throw new IllegalArgumentException(\"This command requires a persistent topic, got: \" + topic);\n}","typeGuard":null,"tryCatchPattern":"try {\n    admin.topics().getStats(topic);\n} catch (IllegalArgumentException e) {\n    log.error(\"{} — use persistent://tenant/namespace/topic\", e.getMessage());\n}","preventionTips":["Always pass fully-qualified topic URLs with the persistent:// scheme in admin scripts","Keep persistent and non-persistent topics in separate config variables/scripts","Check broker default topic domain settings if short names are common in your environment","Shell-validate the scheme prefix before invoking pulsar-admin"],"tags":["cli","pulsar-admin","topic-domain","argument-validation"],"backgroundTag":"invalid-topic-domain","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}