apache/pulsar · critical · RuntimeException

Could not start MetaData topic tailer

Error message

Could not start MetaData topic tailer

What it means

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'.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionMetaDataManager.java:125

            while (reader.hasMessageAvailable()) {
                processMetaDataTopicMessage(reader.readNext());
            }
            this.isInitialized.complete(null);
        } catch (Exception e) {
            log.error().exception(e).log("Failed to initialize meta data store");
            throw new RuntimeException("Failed to initialize Metadata Manager", e);
        }
        log.info("FunctionMetaData Manager initialization complete");
    }

    // Starts the tailer if we are in non-leader mode
    public synchronized void start() {
        if (exclusiveLeaderProducer == null) {
            try {
                // This means that we are in non-leader mode. start function metadata tailer
                initializeTailer();
            } catch (PulsarClientException e) {
                throw new RuntimeException("Could not start MetaData topic tailer", e);
            }
        }
    }

    @Override
    public void close() throws Exception {
        if (this.functionMetaDataTopicTailer != null) {
            this.functionMetaDataTopicTailer.close();
        }
        if (this.exclusiveLeaderProducer != null) {
            this.exclusiveLeaderProducer.close();
        }
    }

    /**
     * Get the function metadata for a function.
     * @param tenant the tenant the function belongs to
     * @param namespace the namespace the function belongs to

View on GitHub (pinned to 820761864e)

Solutions

  1. Ensure the Pulsar broker is reachable and the functions metadata topic exists / can be auto-created
  2. Grant the worker's role read permissions on the functions namespace
  3. Verify the workerConfig's pulsar service URL and metadata topic settings are correct

Example fix

// before: broker down -> tailer fails
// after: verify before start
pulsar-admin topics create persistent://public/functions/metadata
pulsar-admin namespaces grant-permissions public/functions --role functions-worker --actions consume
Defensive patterns

Strategy: retry

Validate before calling

// verify tailer can attach before start
admin.topics().getStats("persistent://public/functions/metadata");
admin.namespaces().getPermissions("public/functions");

Try / catch

try {
    metaDataManager.start();
} catch (RuntimeException e) {
    if (e.getMessage().contains("Could not start MetaData topic tailer")) {
        // PulsarClientException is e.getCause(); retry with backoff or fail leadership
    } else { throw e; }
}

Prevention

When it happens

Trigger: 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.

Common situations: Workers that lost leadership election trying to tail the metadata topic during broker outage; namespace policies blocking reader creation; wrong metadata topic URL configured.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/352b16de34bcc3b0. Report an issue: GitHub.