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

CmdRead.read() maps the --schema-type option to a Schema; this CLI only supports 'auto_consume' (Schema.AUTO_CONSUME) and 'bytes' (Schema.BYTES). Any other value throws IllegalArgumentException before a consumer is created.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdRead.java:148

        if (this.serviceURL.startsWith("ws")) {
            return readFromWebSocket(topic);
        } else {
            return read(topic);
        }
    }

    private int read(String topic) {
        int numMessagesRead = 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 (this.startMessageIdInclusive) {
            LOG.warn("--start-message-id-inclusive has no effect on this version of pulsar-client.");
        }
        if (maxPendingChunkedMessage > 0 || autoAckOldestChunkedMessageOnQueueFull) {
            LOG.warn("Chunked-message knobs (--max_chunked_msg / --auto_ack_chunk_q_full) have no effect "
                    + "on this version of pulsar-client.");
        }

        Checkpoint startPosition = START_EARLIEST.equals(startMessageId)
                ? Checkpoint.earliest() : Checkpoint.latest();

        try (PulsarClient client = clientBuilder.build()) {
            CheckpointConsumerBuilder<?> builder = client.newCheckpointConsumer(schema)
                    .topic(topic)

View on GitHub (pinned to 820761864e)

Solutions

1. Use --schema-type auto_consume to decode payloads per their embedded schema, or bytes for raw payloads.
2. Fix typos — the accepted values are exactly 'bytes' and 'auto_consume' (lowercase, underscore).
3. For richer schema support use the full Java client Consumer with the desired Schema.

Example fix

// before
pulsar-client read my-topic --schema-type json
// after
pulsar-client read my-topic --schema-type auto_consume

// bash
case "$SCHEMA_TYPE" in bytes|auto_consume) ;; *) echo "schema type must be bytes or auto_consume"; exit 1;; esac

function isValidReadSchemaType(v) { return v === 'bytes' || v === 'auto_consume'; }

try { readCmd(schemaType); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("schema type must be")) { /* default to auto_consume and retry */ } else throw e; }

When it happens

Trigger: Running `pulsar-client read <topic> --schema-type json` (or avro, string, int8, etc.) — any value other than the two accepted literals.

Common situations: Copying --schema-type values from full pulsar-client docs into this V5 CLI; expecting JSON/Avro decoding in the read tool; typo like 'auto-consume' vs 'auto_consume'.

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
• schema type must be 'bytes' or 'auto_consume'
• Invalid schema type: ${valueSchema}

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