apache/pulsar · error · Exception

Partitioned topic is not available in effectively_once mode.

Error message

Partitioned topic is not available in effectively_once mode.

What it means

In effectively-once mode, python_instance.process_result publishes results through a producer keyed by the configured sink topic and relies on the message's partition index being negative (i.e. a non-partitioned topic) for dedup guarantees. If get_message_partition_index() is None or >= 0, Pulsar raises Exception('Partitioned topic is not available in effectively_once mode.') because effectively-once delivery isn't supported over a partitioned output topic in this path.

Source

Thrown at pulsar-functions/instance/src/main/python/python_instance.py:325

      if self.auto_ack and self.atleast_once or self.effectively_once:
        consumer.acknowledge(orig_message)
    else:
      error_msg = "Failed to publish to topic [%s] with error [%s] with src message id [%s]" % (topic, result, orig_message.message_id())
      Log.error(error_msg)
      self.stats.incr_total_sys_exceptions(Exception(error_msg))
      # If producer fails send output then send neg ack for input message back to broker
      consumer.negative_acknowledge(orig_message)

  def process_result(self, output, msg):
    if output is not None and self.instance_config.function_details.sink.topic is not None and \
            len(self.instance_config.function_details.sink.topic) > 0:
      if self.output_serde is None:
        self.setup_output_serde()
      if self.effectively_once:
        if self.contextimpl.get_message_partition_index() is None or \
                self.contextimpl.get_message_partition_index() >= 0:
          Log.error("Partitioned topic is not available in effectively_once mode.")
          raise Exception("Partitioned topic is not available in effectively_once mode.")

        producer_id = self.instance_config.function_details.sink.topic
        producer = self.contextimpl.publish_producers.get(producer_id)
        if producer is None:
          self.setup_producer(producer_name=producer_id)
          self.contextimpl.publish_producers[producer_id] = self.producer
          Log.info("Setup producer [%s] successfully in effectively_once mode." % self.producer.producer_name())

      if self.producer is None:
        self.setup_producer()
        Log.info("Setup producer successfully.")

      # only serialize function output when output schema is not set
      output_object = output
      if self.output_schema == DEFAULT_SCHEMA:
        output_object = self.output_serde.serialize(output)

      if output_object is not None:

View on GitHub (pinned to 820761864e)

Solutions

Disable effectivelyOnce if the input topic is partitioned.
Use a non-partitioned input topic when effectively-once semantics are required.
Ensure the message carries a valid (negative, non-partitioned) partition index; check producer/topic setup upstream.
Restructure so effectively-once publishing targets a non-partitioned sink topic.

Example fix

# before (function config)
effectivelyOnce: true  # input topic my-topic has 4 partitions
# after
effectivelyOnce: false
# or consume from non-partitioned 'my-topic-non-partitioned'

Defensive patterns

Strategy: validation

Validate before calling

if effectively_once and (msg.partition_index() is None or msg.partition_index() >= 0):
    raise RuntimeError('effectively-once requires a non-partitioned input topic')

Try / catch

try:
    process(msg)
except Exception as e:
    if 'effectively_once' in str(e):
        logging.error('disable effectivelyOnce or use non-partitioned topic')

Prevention

Don't enable effectivelyOnce for partitioned input topics.
Confirm partition index metadata is present on messages.
Document the effectively-once topic constraint in your function config review checklist.

When it happens

Trigger: Running a Python function with effectivelyOnce=true while the input message comes from a partitioned topic (partition index >= 0) or the index is unavailable (None) — checked in process_result during actual_execution of a normal (non-batch) message.

Common situations: Enabling effectively-once for a function whose input topic is partitioned; upgrading/adding effectivelyOnce config to an existing function consuming partitioned topics; missing message metadata yielding None partition index.

Related errors

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