apache/pulsar · error · InvalidSchemaDataException

Schema ${schemaType} is a client-side schema type

Error message

Schema ${schemaType} is a client-side schema type

What it means

SchemaDataValidator.validateSchemaData rejects schema types that only make sense on the client side: AUTO, AUTO_CONSUME and AUTO_PUBLISH. These are placeholder/auto-resolving types, so a schema claiming one of them cannot be stored in the registry — the real concrete type must be resolved before registration. (NONE/BYTES/EXTERNAL are skipped, KEY_VALUE recurses into key and value schemas.)

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/validator/SchemaDataValidator.java:91

            case DOUBLE:
            case DATE:
            case TIME:
            case TIMESTAMP:
            case INSTANT:
            case LOCAL_DATE:
            case LOCAL_TIME:
            case LOCAL_DATE_TIME:
                PrimitiveSchemaDataValidator.of().validate(schemaData);
                break;
            case NONE:
            case BYTES:
            case EXTERNAL:
                // `NONE`, `BYTES` and `EXTERNAL` schema is not stored
                break;
            case AUTO:
            case AUTO_CONSUME:
            case AUTO_PUBLISH:
                throw new InvalidSchemaDataException(
                    "Schema " + schemaData.getType() + " is a client-side schema type");
            case KEY_VALUE:
                KeyValue<SchemaData, SchemaData> kvSchema =
                    KeyValueSchemaCompatibilityCheck.decodeKeyValueSchemaData(schemaData);
                validateSchemaData(kvSchema.getKey(), allowLegacyJacksonFormat);
                validateSchemaData(kvSchema.getValue(), allowLegacyJacksonFormat);
                break;
            default:
                throw new InvalidSchemaDataException("Unknown schema type : " + schemaData.getType());
        }
    }

    /**
     * Validate a schema data is in a valid form.
     *
     * @param schemaData schema data to validate
     * @throws InvalidSchemaDataException if the schema data is not in a valid form.
     */

View on GitHub (pinned to 820761864e)

Solutions

1. Resolve the concrete schema before registering: use Schema.AUTO_PRODUCE_BYTES(...).getSchemaInfo() only after decoding, or capture the real schema from a message's schema version.
2. Register the actual type explicitly (AVRO/JSON/PROTOBUF_NATIVE/STRING/...) instead of the AUTO type.
3. If the topic should be schemaless, do not register a schema at all (or use NONE) rather than an AUTO type.
4. For KEY_VALUE producers, register the concrete KV schema whose key/value parts are non-AUTO.

Example fix

// before
SchemaInfo info = Schema.AUTO_CONSUME().getSchemaInfo();
admin.schemas().createSchema(topic, info);
// after
SchemaInfo info = Schema.JSON(User.class).getSchemaInfo();
admin.schemas().createSchema(topic, info);

import org.apache.pulsar.common.schema.SchemaType;
if (info.getType() == SchemaType.AUTO
        || info.getType() == SchemaType.AUTO_CONSUME
        || info.getType() == SchemaType.AUTO_PUBLISH) {
    throw new IllegalArgumentException("Resolve AUTO schema to a concrete type before registering: " + info.getType());
}

boolean isStorableType(SchemaType t) {
    return t != SchemaType.AUTO && t != SchemaType.AUTO_CONSUME && t != SchemaType.AUTO_PUBLISH;
}

When it happens

Trigger: Uploading/uploading via REST or the client a SchemaInfo whose type is SchemaType.AUTO, AUTO_CONSUME or AUTO_PUBLISH — e.g. calling admin.schemas().createSchema(topic, schemaInfo) with Schema.AUTO_PRODUCE_BYTES() or Schema.AUTO_CONSUME() info without resolving the underlying concrete schema first.

Common situations: Automation copying the producer's auto schema info straight into the registry; frameworks that pass through client schema objects to admin APIs; code paths where auto schema resolution was skipped because no message had been seen yet.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid schema definition data for primitive schemas :length
• deserialize ProtobufNative Schema failed
• protobuf root message descriptor is null, please recheck roo
• Unknown schema type :
• Invalid schema definition data for string schema : '

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