{"record":{"id":"f4be9a166e6e9a50","repo":"apache/pulsar","slug":"topic-factory-failed-to-create-topic","errorCode":null,"errorMessage":"Topic factory failed to create topic ","messagePattern":"Topic factory failed to create topic ","errorType":"exception","errorClass":"PulsarServerException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java","lineNumber":4619,"sourceCode":"\n    public void recordConnectionUnthrottled() {\n        rateLimitedConnectionsCounter.add(1, ConnectionRateLimitOperationName.UNTHROTTLED.attributes);\n        throttledConnectionsGauge.dec();\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    @VisibleForTesting\n    public <T extends Topic> T newTopic(String topic, ManagedLedger ledger, BrokerService brokerService,\n            Class<T> topicClazz) throws PulsarServerException {\n        if (topicFactory != null) {\n            try {\n                Topic newTopic = topicFactory.create(topic, ledger, brokerService, topicClazz);\n                if (newTopic != null) {\n                    return (T) newTopic;\n                }\n            } catch (Throwable e) {\n                log.warn().attr(\"topic\", topic).exception(e).log(\"Failed to create persistent topic using factory\");\n                throw new PulsarServerException(\"Topic factory failed to create topic \", e);\n            }\n        }\n        return topicClazz == NonPersistentTopic.class ? (T) new NonPersistentTopic(topic, BrokerService.this)\n                : (T) new PersistentTopic(topic, ledger, brokerService);\n    }\n\n    private TopicFactory createPersistentTopicFactory() throws Exception {\n        String topicFactoryClassName = pulsar.getConfig().getTopicFactoryClassName();\n        if (StringUtils.isNotBlank(topicFactoryClassName)) {\n            try {\n                return (TopicFactory) Class.forName(topicFactoryClassName)\n                        .getDeclaredConstructor().newInstance();\n            } catch (Exception e) {\n                log.warn()\n                        .attr(\"topicFactoryClassName\", topicFactoryClassName)\n                        .exception(e)\n                        .log(\"Failed to initialize topic factory class\");\n                throw e;","sourceCodeStart":4601,"sourceCodeEnd":4637,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java#L4601-L4637","documentation":"When a TopicFactory plugin is configured, BrokerService delegates persistent topic creation to it. If the factory throws, or returns null unexpectedly, Pulsar wraps the failure in PulsarServerException with the message 'Topic factory failed to create topic '.","triggerScenarios":"Loading a topic with a custom topic factory configured (topicFactoryClassName broker setting) where factory.create(topic, ledger, brokerService, topicClazz) throws any Throwable.","commonSituations":"Buggy or incompatible custom topic factory plugin (wrong Pulsar version compiled against); factory failing to allocate resources (ledger/bookkeeper errors); factory class returning null for persistent topics.","solutions":["Read the chained cause 'e' in the exception for the real failure from the factory","Verify the topic factory plugin is compiled against the same Pulsar version and implements TopicFactory correctly","Fix or remove the topicFactoryClassName broker configuration to fall back to the default topic implementation","Add logging/tests in the factory to surface why create() throws or returns null"],"exampleFix":"// broker.conf\n// before\ntopicFactoryClassName=com.example.MyTopicFactory\n// after (disable broken factory, use default implementation)\n#topicFactoryClassName=","handlingStrategy":"try-catch","validationCode":"// verify factory configuration before enabling\nassert brokerConfig.getTopicFactoryClassName() != null\n    && Class.forName(brokerConfig.getTopicFactoryClassName()).newInstance() instanceof TopicFactory;","typeGuard":null,"tryCatchPattern":"try {\n    T topic = brokerService.getTopic(...);\n} catch (PulsarServerException e) {\n    log.error(\"Topic factory failed\", e.getCause());\n}","preventionTips":["Compile custom TopicFactory plugins against the exact broker Pulsar version","Test the factory's create() path in isolation before deploying","Keep the factory's dependencies shaded and up to date"],"tags":["java","broker","topic-factory","plugin","topic-creation"],"backgroundTag":"topic-factory-creation-failed","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"}