What causes "The schema class %s does not exist" in apache/pulsar?

Correct the schema-type string to the exact FQCN of the class

apache/pulsar · error · IllegalArgumentException

The schema class %s does not exist

Error message

The schema class %s does not exist

What it means

ValidatorUtils.validateSchema resolves the user-supplied schemaType as a class via ByteBuddy's TypePool; if the type cannot be found on the classpath (NoSuchTypeException) it throws this IllegalArgumentException. Built-in schema types (e.g. primitives, Avro/JSON strings) are skipped before this check.

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/ValidatorUtils.java:49

import org.apache.pulsar.common.functions.MessagePayloadProcessorConfig;
import org.apache.pulsar.common.schema.SchemaType;
import org.apache.pulsar.functions.api.SerDe;

@CustomLog
public class ValidatorUtils {
    private static final String DEFAULT_SERDE = "org.apache.pulsar.functions.api.utils.DefaultSerDe";

    public static void validateSchema(String schemaType, TypeDefinition typeArg, TypePool typePool,
                                      boolean input) {
        if (isEmpty(schemaType) || getBuiltinSchemaType(schemaType) != null) {
            // If it's empty, we use the default schema and no need to validate
            // If it's built-in, no need to validate
        } else {
            TypeDescription schemaClass = null;
            try {
                schemaClass = typePool.describe(schemaType).resolve();
            } catch (TypePool.Resolution.NoSuchTypeException e) {
                throw new IllegalArgumentException(
                        String.format("The schema class %s does not exist", schemaType));
            }
            if (!schemaClass.asErasure().isAssignableTo(Schema.class)) {
                throw new IllegalArgumentException(
                        String.format("%s does not implement %s", schemaType, Schema.class.getName()));
            }
            validateSchemaType(schemaClass, typeArg, typePool, input);
        }
    }

    private static SchemaType getBuiltinSchemaType(String schemaTypeOrClassName) {
        try {
            return SchemaType.valueOf(schemaTypeOrClassName.toUpperCase());
        } catch (IllegalArgumentException e) {
            // schemaType is not referring to builtin type
            return null;
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

Correct the schema-type string to the exact FQCN of the class
Package the custom Schema class into the function jar and resubmit
Use a built-in schema type (STRING, JSON, AVRO, INT64, ...) instead of a custom class name

Example fix

// before
// --schema-type com.acme.MySchema // class missing from jar
// after
// add MySchema.class to the function jar, or:
// --schema-type org.apache.pulsar.common.schema.SchemaType.JSON

Defensive patterns

Strategy: validation

Validate before calling

// confirm the schema class is loadable before submission
try {
    Class.forName(schemaType);
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Schema class not in jar: " + schemaType);
}

Try / catch

try {
    ValidatorUtils.validateSchema(schemaType, typeArg, typePool, input);
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith("does not exist")) {
        // fall back to a built-in schema type or fix the FQCN
    }
    throw e;
}

Prevention

Prefer built-in SchemaType values unless a custom Schema is genuinely needed
Verify the custom Schema class is packaged in the function jar
Copy FQCNs from the IDE instead of typing them

When it happens

Trigger: Setting --schema-type (or sourceSchemaType in function config) to a custom Schema implementation class that is not present in the function worker's classpath, or to a misspelled/nonexistent class name.

Common situations: Typing a custom schema class FQCN with a typo; forgetting to include the custom schema class in the uploaded function jar; referencing a schema class removed in a Pulsar client upgrade.

Related errors

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