apache/seatunnel · error · PulsarConnectorException

SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED

SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED

Error message

Single-table Pulsar source must configure 'subscription.name'.

What it means

PulsarSourceFactory.validateSourceOptions enforces that a single-table Pulsar source (no multi-table 'table_configs' present) always declares a subscription name ('subscription.name'). Pulsar consumers need a subscription to track cursors, so without it the source cannot be built and this CONFIG_VALIDATION_FAILED error is thrown.

Source

Thrown at seatunnel-connectors-v2/connector-pulsar/src/main/java/org/apache/seatunnel/connectors/seatunnel/pulsar/source/PulsarSourceFactory.java:115

    @Override
    public <T, SplitT extends SourceSplit, StateT extends Serializable>
            TableSource<T, SplitT, StateT> createSource(TableSourceFactoryContext context) {
        validateSourceOptions(context.getOptions());
        CatalogTable catalogTable;
        if (context.getOptions().getOptional(PulsarSourceOptions.SCHEMA).isPresent()) {
            catalogTable = CatalogTableUtil.buildWithConfig(context.getOptions());
        } else {
            catalogTable = CatalogTableUtil.buildSimpleTextTable();
        }
        return () ->
                (SeaTunnelSource<T, SplitT, StateT>)
                        new PulsarSource(context.getOptions(), catalogTable);
    }

    private void validateSourceOptions(ReadonlyConfig config) {
        if (!config.getOptional(TableSchemaOptions.TABLE_CONFIGS).isPresent()
                && !config.getOptional(PulsarSourceOptions.SUBSCRIPTION_NAME).isPresent()) {
            throw new PulsarConnectorException(
                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                    String.format(
                            "Single-table Pulsar source must configure '%s'.",
                            PulsarSourceOptions.SUBSCRIPTION_NAME.key()));
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Add 'subscription.name = "my-subscription"' to the Pulsar source options.
If you intended multi-table mode, configure 'table_configs' instead and give each table its subscription.
Check for renamed/legacy option keys in old configs and update to the current 'subscription.name' key.
Also verify the subscription exists (or set subscription-level options like initial position) on the Pulsar side.

Example fix

// before
Pulsar {
  service.url = "pulsar://localhost:6650"
  topic = "persistent://public/default/my-topic"
}
// after
Pulsar {
  service.url = "pulsar://localhost:6650"
  topic = "persistent://public/default/my-topic"
  subscription.name = "seatunnel-sub"
}

Defensive patterns

Strategy: validation

Validate before calling

boolean multiTable = cfg.getOptional("table_configs").isPresent();
if (!multiTable && cfg.getOptional("subscription.name").isEmpty())
    throw new IllegalArgumentException("single-table Pulsar source needs 'subscription.name'");

Prevention

Treat subscription.name as mandatory for single-table Pulsar sources.
Migrate legacy consumer-group style keys to subscription.name.
Validate config templates against the current connector option keys after upgrades.

When it happens

Trigger: Creating a Pulsar source via the factory without 'table_configs' AND without PulsarSourceOptions.SUBSCRIPTION_NAME configured — i.e. a single-table config missing 'subscription.name'.

Common situations: Users migrating from older SeaTunnel versions where the option key was different (older configs used 'consumer-group' style keys) or simply forgetting that Pulsar, unlike Kafka, requires an explicit subscription name.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/d67fac26361a8587. Report an issue: GitHub.