{"record":{"id":"79e7878ae65fa5d5","repo":"apache/pulsar","slug":"failed-to-initialize-metadata-manager","errorCode":null,"errorMessage":"Failed to initialize Metadata Manager","messagePattern":"Failed to initialize Metadata Manager","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionMetaDataManager.java","lineNumber":113,"sourceCode":"    /*\n     * Public methods. Please use these methods if references FunctionMetaManager from an external class\n     */\n\n    /**\n     * Initializes the FunctionMetaDataManager.\n     * We create a new reader\n     */\n    public synchronized void initialize() {\n        try (Reader<byte[]> reader = FunctionMetaDataTopicTailer.createReader(\n                workerConfig, pulsarClient.newReader(), MessageId.earliest)) {\n            // read all existing messages\n            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 {","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionMetaDataManager.java#L95-L131","documentation":"FunctionMetaDataManager.initialize replays all messages from the function metadata topic before the worker serves requests. Any failure (reader creation, read errors, processing exceptions) is logged and rethrown as RuntimeException 'Failed to initialize Metadata Manager', aborting worker startup.","triggerScenarios":"Worker startup when the metadata topic (persistent://public/functions/metadata) cannot be read: broker unreachable, topic permissions issues, corrupted messages, or processMetaDataTopicMessage throwing on a bad record.","commonSituations":"BookKeeper/broker outage during worker start; ACLs preventing the worker from reading the metadata topic; an old/poison message in the metadata topic failing deserialization or validation.","solutions":["Check connectivity to the Pulsar broker/BookKeeper and ensure the functions metadata topic exists and is readable","Fix topic authorization for the worker's role on the metadata topic","Inspect the metadata topic for a poison message; skip/repair it, or reinitialize the functions state"],"exampleFix":"// startup log shows cause 'Failed to read from metadata topic'\n// fix: grant worker role read access\npulsar-admin namespaces grant-permissions public/functions --role functions-worker --actions read,produce","handlingStrategy":"try-catch","validationCode":"// before starting worker\npulsarAdmin.namespaces().getPermissions(\"public/functions\"); // verify topic access\nPulsarAdmin admin = ...;\nadmin.topics().getStats(\"persistent://public/functions/metadata\"); // topic exists/readable","typeGuard":null,"tryCatchPattern":"try {\n    worker.start();\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"Failed to initialize Metadata Manager\")) {\n        // check broker health / metadata topic permissions, then restart worker\n        log.error(\"metadata manager init failed\", e.getCause());\n    } else { throw e; }\n}","preventionTips":["Monitor broker/BookKeeper health before and during worker startup","Grant the worker role read+produce on the functions namespace","Alert on worker startup failures caused by unreadable metadata topics"],"tags":["pulsar-functions","worker","metadata","startup","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-14T00:17:10.932Z"}