{"record":{"id":"8440aa3bbf5a5894","repo":"apache/rocketmq","slug":"the-factory-object-clientid-has-been-created-be","errorCode":null,"errorMessage":"The Factory object[{clientId}] has been created before, and failed.","messagePattern":"The Factory object\\[(.+?)\\] has been created before, and failed\\.","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/factory/MQClientInstance.java","lineNumber":371,"sourceCode":"                        // Start pull service\n                        this.pullMessageService.start();\n                        // Start rebalance service\n                        this.rebalanceService.start();\n                        // Start push service\n                        this.defaultMQProducer.getDefaultMQProducerImpl().start(false);\n                        log.info(\"the client factory [{}] start OK\", this.clientId);\n                        this.serviceState = ServiceState.RUNNING;\n                    } catch (MQClientException | RuntimeException | Error e) {\n                        // Do not apply the normal shutdown registration guards here: a factory that never reached\n                        // RUNNING cannot serve any registered client, and its partially started resources must stop.\n                        // Existing holders still observe START_FAILED; a later manager lookup may create a replacement.\n                        cleanupAfterStartFailure(e);\n                        MQClientManager.getInstance().removeClientFactory(this.clientId, this);\n                        throw e;\n                    }\n                    break;\n                case START_FAILED:\n                    throw new MQClientException(\"The Factory object[\" + this.getClientId() + \"] has been created before, and failed.\", null);\n                default:\n                    break;\n            }\n        }\n    }\n\n    private void cleanupAfterStartFailure(Throwable cause) {\n        runCleanup(this.scheduledExecutorService::shutdownNow, cause);\n        if (this.concurrentHeartbeatExecutor != null) {\n            runCleanup(this.concurrentHeartbeatExecutor::shutdownNow, cause);\n        }\n        runCleanup(() -> this.defaultMQProducer.getDefaultMQProducerImpl().shutdown(false), cause);\n        runCleanup(() -> this.pullMessageService.shutdown(true), cause);\n        runCleanup(this.rebalanceService::shutdown, cause);\n        runCleanup(this.mQClientAPIImpl::shutdown, cause);\n    }\n\n    private void startScheduledTask() {","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/factory/MQClientInstance.java#L353-L389","documentation":"Thrown by MQClientInstance.start() when start() is called on a client-instance whose previous start attempt already failed (state START_FAILED). Each clientId maps to one shared MQClientInstance; a failed start leaves the instance registered but unusable, so any subsequent producer/consumer sharing that clientId gets this exception instead of a retry. A failed instance must be fully shut down (removed from the manager) before a fresh start can succeed.","triggerScenarios":"Producer/consumer A with clientId X fails to start (e.g. cannot reach NameServer); code catches the exception and calls start() again on the same object, or creates another consumer that hashes to the same clientId — the switch hits case START_FAILED and throws immediately.","commonSituations":"Retry loops around consumer.start() after a transient NameServer outage; hot re-creation of consumers/producer in the same JVM reusing an IP@instance naming pattern that collides on clientId; frameworks (Spring context refresh) restarting beans whose instance previously failed; mixing manual shutdown semantics so the failed instance is never removed from MQClientManager.","solutions":["On start failure, fully release the failed instance before retrying: call shutdown() on the consumer/producer whose start failed (post-patch, the factory itself cleans up and deregisters from MQClientManager), then create a fresh consumer/producer object","Give every client a unique instanceName (setInstanceName) so a failed instance cannot poison another client sharing the same clientId","Do not call start() twice on the same object after a failure — create a new instance instead","Fix the root cause of the first failure (NameServer address, ACL) before attempting restart"],"exampleFix":"// before\ntry { consumer.start(); } catch (Exception e) { /* ignored */ }\nconsumer.start(); // -> The Factory object[...] has been created before, and failed.\n// after\ntry { consumer.start(); }\ncatch (MQClientException e) {\n    consumer.shutdown(); // release the failed instance\n    consumer = buildConsumer(); // fresh object, unique instanceName\n    consumer.start();\n}","handlingStrategy":"fallback","validationCode":"// before any restart attempt, ensure the previous failed instance was released\n// (post-cleanup builds deregister from MQClientManager automatically)\nif (previousConsumer != null && previousConsumer.getDefaultMQPushConsumerImpl() != null) previousConsumer.shutdown();\n// and keep instanceName unique per client\nconsumer.setInstanceName(\"order-consumer-\" + UUID.randomUUID());","typeGuard":null,"tryCatchPattern":"try { consumer.start(); } catch (MQClientException e) {\n    if (e.getMessage().contains(\"has been created before, and failed\")) {\n        consumer.shutdown();              // release poisoned instance\n        consumer = buildNewConsumer();     // fresh object, unique instanceName\n        consumer.start();\n    } else throw e;\n}","preventionTips":["Never call start() twice on a client whose start failed — build a new one","Set a unique instanceName per consumer/producer to avoid clientId collisions","Fix root-cause start failures (namesrvAddr, ACL) before restart loops","Frameworks restarting beans should fully destroy the failed bean first"],"tags":["rocketmq","lifecycle","startup","client-instance","retry-misuse"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}