apache/pulsar · error · RuntimeException

Schema definition must specify pojo class or schema json def

Error message

Schema definition must specify pojo class or schema json definition

What it means

createAvroSchema requires its schemaDefinition to carry either a pojo class or an explicit Avro JSON schema definition. If neither is present there is nothing to derive the schema from, so a RuntimeException is thrown. This indicates the SchemaDefinition builder was used without setting the underlying schema source.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/schema/util/SchemaUtil.java:95

            try {
                Field validateDefaultsField = Schema.class.getDeclaredField("VALIDATE_DEFAULTS");
                validateDefaultsField.setAccessible(true);
                validateDefaults = (ThreadLocal<Boolean>) validateDefaultsField.get(null);
            } catch (NoSuchFieldException | IllegalAccessException e) {
                throw new RuntimeException("Cannot disable validation of default values", e);
            }

            final boolean savedValidateDefaults = validateDefaults.get();

            try {
                // Disable validation of default values for compatibility
                validateDefaults.set(false);
                return extractAvroSchema(schemaDefinition, pojo);
            } finally {
                validateDefaults.set(savedValidateDefaults);
            }
        } else {
            throw new RuntimeException("Schema definition must specify pojo class or schema json definition");
        }
    }

    public static Schema extractAvroSchema(SchemaDefinition schemaDefinition, Class pojo) {
        try {
            return parseAvroSchema(pojo.getDeclaredField("SCHEMA$").get(null).toString());
        } catch (NoSuchFieldException | IllegalAccessException | IllegalArgumentException ignored) {
            ReflectData reflectData = schemaDefinition.getAlwaysAllowNull()
                     ? new ReflectData.AllowNull()
                     : new ReflectData();
            AvroSchema.addLogicalTypeConversions(reflectData, schemaDefinition.isJsr310ConversionEnabled(), false);
            try {
                return reflectData.getSchema(pojo);
            } catch (RuntimeException e) {
                throw new SchemaSerializationException(
                        "Unable to create Avro schema for class " + pojo.getName(), e);
            }
        }

View on GitHub (pinned to 820761864e)

Solutions

Set the pojo: SchemaDefinition.<T>builder().withPojo(MyPojo.class).build().
Alternatively supply the schema JSON definition string in the SchemaDefinition builder.
If constructing SchemaDefinition manually, verify the pojo/schemaJson field is non-null before passing it on.

Example fix

// before
SchemaDefinition<MyPojo> def = SchemaDefinition.<MyPojo>builder().build();
Schema schema = Schema.AVRO(def);
// after
SchemaDefinition<MyPojo> def = SchemaDefinition.<MyPojo>builder().withPojo(MyPojo.class).build();
Schema schema = Schema.AVRO(def);

Defensive patterns

Strategy: validation

Validate before calling

if (schemaDefinition.getPojo() == null && schemaDefinition.getSchemaDefinition() == null) {
    throw new IllegalArgumentException("SchemaDefinition needs pojo or schema json");
}

Try / catch

try {
    Schema<T> s = Schema.AVRO(definition);
} catch (RuntimeException e) {
    if (e.getMessage().contains("must specify pojo class")) {
        definition = SchemaDefinition.<T>builder().withPojo(pojoClass).build();
    }
}

Prevention

Always call withPojo(...) or the schema json setter on SchemaDefinition.builder()
Add a unit test that builds each schema at startup
Avoid hand-rolling SchemaDefinition; use Schema.AVRO(Class) directly

When it happens

Trigger: Building a SchemaDefinition without calling pojo(...) or schemaDefinitionBuilder with schema json: e.g. SchemaDefinition.builder().build() passed to createAvroSchema / parseSchemaInfo.

Common situations: Custom schema-building code that builds SchemaDefinition programmatically but forgets .withPojo(clazz); refactors that dropped the pojo argument; copying builder code and omitting the schema json.

Related errors

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