apache/pulsar · error · IllegalArgumentException

schema type must be 'bytes' or 'auto_consume'

Error message

schema type must be 'bytes' or 'auto_consume'

What it means

CmdConsume.consume builds the consumer Schema from the --schema-type argument and only accepts 'auto_consume' (Schema.autoConsume) or 'bytes' (Schema.bytes). Any other string throws IllegalArgumentException before the consumer is created, because this CLI build cannot materialize other schema types.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdConsume.java:188

        if (this.serviceURL.startsWith("ws")) {
            return consumeFromWebSocket(topic);
        } else {
            return consume(topic);
        }
    }

    private int consume(String topic) {
        int numMessagesConsumed = 0;
        int returnCode = 0;

        final Schema<?> schema;
        if ("auto_consume".equals(schemaType)) {
            schema = Schema.autoConsume();
        } else if ("bytes".equals(schemaType)) {
            schema = Schema.bytes();
        } else {
            throw new IllegalArgumentException("schema type must be 'bytes' or 'auto_consume'");
        }
        if (!poolMessages) {
            LOG.info("--pool-messages has no effect on this version of pulsar-client.");
        }
        if (subscriptionMode == SubscriptionMode.NonDurable) {
            LOG.warn("--subscription-mode NonDurable is not supported by this version of pulsar-client; "
                    + "a durable subscription is used instead.");
        }
        if (subscriptionType == SubscriptionType.Exclusive || subscriptionType == SubscriptionType.Failover) {
            // The V5 StreamConsumer (ordered, single-reader) requires a scalable-topic subscription
            // controller, which regular topics do not have; only the QueueConsumer works against
            // both regular and scalable topics. So all subscription types use a QueueConsumer here
            // and Exclusive/Failover get work-queue (Shared-style) semantics rather than ordered.
            LOG.warn("--subscription-type {} : this version of pulsar-client consumes via a work-queue "
                    + "(Shared-style) subscription; exclusive/failover ordering is not preserved.",
                    subscriptionType);
        }
        if (maxPendingChunkedMessage > 0 || autoAckOldestChunkedMessageOnQueueFull) {

View on GitHub (pinned to 820761864e)

Solutions

1. Use --schema-type auto_consume to decode using the topic's schema information
2. Use --schema-type bytes to receive raw payload bytes
3. Exact spelling matters: 'bytes' or 'auto_consume', case-sensitive equals check

Example fix

// before
--schema-type json
// after
--schema-type auto_consume

if (!("bytes".equals(schemaType) || "auto_consume".equals(schemaType)))
    throw new IllegalArgumentException("--schema-type must be 'bytes' or 'auto_consume', got: " + schemaType);

static boolean isSupportedConsumeSchemaType(String s) {
    return "bytes".equals(s) || "auto_consume".equals(s);
}

try {
    return consume(topic, schemaType);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("schema type must be")) {
        LOG.warn("Unsupported --schema-type '{}'; falling back to auto_consume", schemaType);
        return consume(topic, "auto_consume");
    } else { throw e; }
}

When it happens

Trigger: Passing --schema-type json, avro, string, etc. to the consume command; or an misspelled variant like 'auto-consume'.

Common situations: Copying --schema-type from producer docs where json/avro are valid there; expecting the CLI to deserialize AVRO payloads natively; older scripts written against a CLI build that accepted more types.

Related errors

• Only one or neither of --version and --all-version can be sp
• Option --version must be greater than 0, but found %d
• Invalid schema type %s. Valid options are: avro, json
• Subscription name is not provided.
• Number of messages should be zero or positive.

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