apache/pulsar · error · IllegalArgumentException

KeyValue schemas (--key-value-encoding-type) are not support

Error message

KeyValue schemas (--key-value-encoding-type) are not supported by this version of pulsar-client; produce with a plain value schema (-vs bytes|string|avro:<def>|json:<def>) instead.

What it means

This V5-based pulsar-client CLI does not implement KeyValue schema support, so if the user passes a non-default --key-value-encoding-type the command fails fast with IllegalArgumentException rather than producing incorrectly encoded messages. Use a plain value schema instead.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdProduce.java:264

        if (this.numTimesProduce <= 0) {
            throw new CommandLine.ParameterException(commandSpec.commandLine(),
                    "Number of times need to be positive number.");
        }

        if (messages.size() > 0) {
            messages = messages.stream().map(str -> str.split(separator)).flatMap(Stream::of).toList();
        }

        if (messages.size() == 0 && messageFileNames.size() == 0) {
            throw new CommandLine.ParameterException(commandSpec.commandLine(),
                    "Please supply message content with either --messages or --files");
        }

        if (keyValueEncodingType == null) {
            keyValueEncodingType = KEY_VALUE_ENCODING_TYPE_NOT_SET;
        } else if (!KEY_VALUE_ENCODING_TYPE_NOT_SET.equals(keyValueEncodingType)) {
            // KeyValue schemas are not yet supported by the V5-based pulsar-client.
            throw new IllegalArgumentException("KeyValue schemas (--key-value-encoding-type) are not "
                    + "supported by this version of pulsar-client; produce with a plain value schema "
                    + "(-vs bytes|string|avro:<def>|json:<def>) instead.");
        }

        int totalMessages = (messages.size() + messageFileNames.size()) * numTimesProduce;
        if (totalMessages > MAX_MESSAGES) {
            String msg = "Attempting to send " + totalMessages + " messages. Please do not send more than "
                    + MAX_MESSAGES + " messages";
            throw new IllegalArgumentException(msg);
        }

        if (this.serviceURL.startsWith("ws")) {
            return publishToWebSocket(topic);
        } else {
            return publish(topic);
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Remove --key-value-encoding-type from the command line.
2. Produce with a plain value schema via -vs, e.g. -vs bytes, -vs string, -vs 'avro:<schema-def>' or -vs 'json:<schema-def>'.
3. If you need KeyValue semantics, use a full pulsar-client distribution/version that supports KeyValue schemas instead of this V5-based CLI.

Example fix

// before
pulsar-client produce t -m '{"a":1}' --key-value-encoding-type INLINE
// after
pulsar-client produce t -m '{"a":1}' -vs 'json:{"type":"record","name":"R","fields":[{"name":"a","type":"int"}]}'

// reject the unsupported option before running
if [[ "$*" == *--key-value-encoding-type* ]]; then echo 'KeyValue not supported; use -vs bytes|string|avro:|json:'; exit 1; fi

try { produce(args); } catch (IllegalArgumentException e) { if (e.getMessage().contains("KeyValue schemas")) { /* drop the option and retry with -vs ... */ } else throw e; }

When it happens

Trigger: Running CmdProduce.run() with --key-value-encoding-type set to anything other than the not-set sentinel value (e.g. INLINE or SEPARATED).

Common situations: Porting old produce scripts that used KeyValue topics; users who think they must set an encoding type for JSON/Avro; copy-pasted commands from docs targeting a full (non-V5) client.

Related errors

• AutoConsumeSchema is not supported with schemaId
• The schema is not a KeyValueSchema
• External schema cannot be used with other Pulsar struct sche
• This method cannot be used under this SEPARATED encoding typ
• No key schema info or value schema info : key = ${keySchema.

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