apache/beam · error · ValueError

Only one of topic or subscription should be provided.

Error message

Only one of topic or subscription should be provided.

What it means

The PubSub source constructor validates that exactly one of 'topic' or 'subscription' is provided; here the mutual-exclusion check found both supplied (the companion check fires when neither is), because a read cannot be bound to two endpoints at once.

Source

Thrown at sdks/python/apache_beam/io/gcp/pubsub.py:540

      topic: Optional[str] = None,
      subscription: Optional[str] = None,
      id_label: Optional[str] = None,
      with_attributes: bool = False,
      timestamp_attribute: Optional[str] = None):
    self.coder = coders.BytesCoder()
    self.full_topic = topic
    self.full_subscription = subscription
    self.topic_name = None
    self.subscription_name = None
    self.id_label = id_label
    self.with_attributes = with_attributes
    self.timestamp_attribute = timestamp_attribute

    # Perform some validation on the topic and subscription.
    if not (topic or subscription):
      raise ValueError('Either a topic or subscription must be provided.')
    if topic and subscription:
      raise ValueError('Only one of topic or subscription should be provided.')

    if topic:
      self.project, self.topic_name = parse_topic(topic)
    if subscription:
      self.project, self.subscription_name = parse_subscription(subscription)

  def display_data(self):
    return {
        'id_label': DisplayDataItem(self.id_label,
                                    label='ID Label Attribute').drop_if_none(),
        'topic': DisplayDataItem(self.full_topic,
                                 label='Pubsub Topic').drop_if_none(),
        'subscription': DisplayDataItem(
            self.full_subscription, label='Pubsub Subscription').drop_if_none(),
        'with_attributes': DisplayDataItem(
            self.with_attributes, label='With Attributes').drop_if_none(),
        'timestamp_attribute': DisplayDataItem(
            self.timestamp_attribute,

View on GitHub (pinned to 12126d8942)

Solutions

1. Supply only one of topic or subscription
2. If both config values exist, choose one explicitly (e.g. prefer subscription) and drop the other
3. Unify configuration so a single key determines the source

Example fix

// before
ReadFromPubSub(topic='projects/p/topics/t', subscription='projects/p/subscriptions/s')
// after
ReadFromPubSub(subscription='projects/p/subscriptions/s')

assert not (topic and subscription), 'pass only one of topic or subscription'

try:
    beam.io.ReadFromPubSub(topic=topic, subscription=subscription)
except ValueError as e:
    if 'Only one of topic or subscription' in str(e):
        topic = None  # prefer subscription
    else:
        raise

When it happens

Trigger: ReadFromPubSub(topic=..., subscription=...) with both non-None; config merging where defaults for topic and an explicit subscription coexist.

Common situations: Copy-paste code leaving both arguments populated; combining a default topic with an override subscription from two config layers; misunderstanding that both can be given for flexibility.

Related errors

• Either data (%r) or attributes (%r) must be set.
• PubSub topic must be in the form "projects/<project>/topics/
• Invalid PubSub project name: %r.
• PubSub subscription must be in the form "projects/<project>/
• Either a topic or subscription must be provided.

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/d64eda52af50139f. Report an issue: GitHub.