apache/pulsar · error · InvalidSchemaDataException

Invalid schema definition data for string schema : '

Error message

Invalid schema definition data for string schema : '

What it means

StringSchemaDataValidator.validate requires STRING schema definition bytes to be empty; the only tolerated non-empty value is the literal string "null" (Python's py None sent as schema data). Any other payload is rejected with InvalidSchemaDataException embedding the offending string. Like primitives, the STRING type carries no schema definition.

Source

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

    public static final StringSchemaDataValidator of() {
        return INSTANCE;
    }

    private static final StringSchemaDataValidator INSTANCE = new StringSchemaDataValidator();

    private static final String PY_NONE_SCHEMA_INFO = "null";

    private StringSchemaDataValidator() {}

    @Override
    public void validate(SchemaData schemaData) throws InvalidSchemaDataException {
        byte[] data = schemaData.getData();
        if (null != data && data.length > 0) {
            // python send 'null' string as schema data
            String schemaDataStr = new String(data, UTF_8);
            if (!PY_NONE_SCHEMA_INFO.equals(schemaDataStr)) {
                throw new InvalidSchemaDataException("Invalid schema definition data for string schema : '"
                    + schemaDataStr + "'");
            }
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Set the schema data to an empty byte array for STRING schemas (or, from Python clients, "null" is tolerated but empty is preferred).
2. If you have real content, the schema isn't STRING — register as AVRO/JSON instead.
3. Fix the constructing code so it calls data(new byte[0]) when the type is STRING.

Example fix

// before
SchemaInfo info = SchemaInfoImpl.builder().type(SchemaType.STRING)
    .data("utf8-string".getBytes(UTF_8)).build();
// after
SchemaInfo info = SchemaInfoImpl.builder().type(SchemaType.STRING)
    .data(new byte[0]).build();

if (info.getType() == SchemaType.STRING
        && info.getData() != null && info.getData().length > 0
        && !"null".equals(new String(info.getData(), java.nio.charset.StandardCharsets.UTF_8))) {
    throw new IllegalArgumentException("STRING schema must have empty schema data");
}

boolean validStringSchemaData(SchemaInfo info) {
    byte[] d = info.getData();
    return d == null || d.length == 0 || "null".equals(new String(d, java.nio.charset.StandardCharsets.UTF_8));
}

When it happens

Trigger: Registering a schema with type STRING (or as part of a KEY_VALUE schema whose side is STRING) while supplying non-empty schema data other than "null" — e.g. SchemaInfo built with data = "string".getBytes() or a leftover encoding definition.

Common situations: Python clients historically sending b'null' (explicitly tolerated); Java tooling copying an Avro SchemaInfo and changing only the type to STRING; tests populating data with placeholder text; framework-generated info that always sets a definition.

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
• Schema ${schemaType} is a client-side schema type
• Unknown schema type :

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