{"record":{"id":"352b16de34bcc3b0","repo":"apache/pulsar","slug":"could-not-start-metadata-topic-tailer","errorCode":null,"errorMessage":"Could not start MetaData topic tailer","messagePattern":"Could not start MetaData topic tailer","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionMetaDataManager.java","lineNumber":125,"sourceCode":"            while (reader.hasMessageAvailable()) {\n                processMetaDataTopicMessage(reader.readNext());\n            }\n            this.isInitialized.complete(null);\n        } catch (Exception e) {\n            log.error().exception(e).log(\"Failed to initialize meta data store\");\n            throw new RuntimeException(\"Failed to initialize Metadata Manager\", e);\n        }\n        log.info(\"FunctionMetaData Manager initialization complete\");\n    }\n\n    // Starts the tailer if we are in non-leader mode\n    public synchronized void start() {\n        if (exclusiveLeaderProducer == null) {\n            try {\n                // This means that we are in non-leader mode. start function metadata tailer\n                initializeTailer();\n            } catch (PulsarClientException e) {\n                throw new RuntimeException(\"Could not start MetaData topic tailer\", e);\n            }\n        }\n    }\n\n    @Override\n    public void close() throws Exception {\n        if (this.functionMetaDataTopicTailer != null) {\n            this.functionMetaDataTopicTailer.close();\n        }\n        if (this.exclusiveLeaderProducer != null) {\n            this.exclusiveLeaderProducer.close();\n        }\n    }\n\n    /**\n     * Get the function metadata for a function.\n     * @param tenant the tenant the function belongs to\n     * @param namespace the namespace the function belongs to","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionMetaDataManager.java#L107-L143","documentation":"FunctionMetaDataManager.start starts the metadata topic tailer when the worker is in non-leader mode (no exclusive leader producer). If initializeTailer() throws a PulsarClientException (e.g. subscription/reader creation fails), it is wrapped in RuntimeException 'Could not start MetaData topic tailer'.","triggerScenarios":"Calling start() in non-leader mode when the Pulsar client cannot create the reader/subscription on the metadata topic: broker down, topic missing and auto-creation disabled, authorization failure.","commonSituations":"Workers that lost leadership election trying to tail the metadata topic during broker outage; namespace policies blocking reader creation; wrong metadata topic URL configured.","solutions":["Ensure the Pulsar broker is reachable and the functions metadata topic exists / can be auto-created","Grant the worker's role read permissions on the functions namespace","Verify the workerConfig's pulsar service URL and metadata topic settings are correct"],"exampleFix":"// before: broker down -> tailer fails\n// after: verify before start\npulsar-admin topics create persistent://public/functions/metadata\npulsar-admin namespaces grant-permissions public/functions --role functions-worker --actions consume","handlingStrategy":"retry","validationCode":"// verify tailer can attach before start\nadmin.topics().getStats(\"persistent://public/functions/metadata\");\nadmin.namespaces().getPermissions(\"public/functions\");","typeGuard":null,"tryCatchPattern":"try {\n    metaDataManager.start();\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"Could not start MetaData topic tailer\")) {\n        // PulsarClientException is e.getCause(); retry with backoff or fail leadership\n    } else { throw e; }\n}","preventionTips":["Ensure brokers are up and metadata topic auto-creation is enabled or topic pre-created","Give the worker role consume permission on the functions namespace","Add retry-with-backoff around worker startup for transient client errors"],"tags":["pulsar-functions","worker","metadata","tailer","pulsar-client"],"backgroundTag":"metadata-store-unavailable","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"}