{"record":{"id":"9e7871e347c7f82f","repo":"apache/pulsar","slug":"the-schema-class-s-does-not-exist","errorCode":null,"errorMessage":"The schema class %s does not exist","messagePattern":"The schema class (.+?) does not exist","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/ValidatorUtils.java","lineNumber":49,"sourceCode":"import org.apache.pulsar.common.functions.MessagePayloadProcessorConfig;\nimport org.apache.pulsar.common.schema.SchemaType;\nimport org.apache.pulsar.functions.api.SerDe;\n\n@CustomLog\npublic class ValidatorUtils {\n    private static final String DEFAULT_SERDE = \"org.apache.pulsar.functions.api.utils.DefaultSerDe\";\n\n    public static void validateSchema(String schemaType, TypeDefinition typeArg, TypePool typePool,\n                                      boolean input) {\n        if (isEmpty(schemaType) || getBuiltinSchemaType(schemaType) != null) {\n            // If it's empty, we use the default schema and no need to validate\n            // If it's built-in, no need to validate\n        } else {\n            TypeDescription schemaClass = null;\n            try {\n                schemaClass = typePool.describe(schemaType).resolve();\n            } catch (TypePool.Resolution.NoSuchTypeException e) {\n                throw new IllegalArgumentException(\n                        String.format(\"The schema class %s does not exist\", schemaType));\n            }\n            if (!schemaClass.asErasure().isAssignableTo(Schema.class)) {\n                throw new IllegalArgumentException(\n                        String.format(\"%s does not implement %s\", schemaType, Schema.class.getName()));\n            }\n            validateSchemaType(schemaClass, typeArg, typePool, input);\n        }\n    }\n\n    private static SchemaType getBuiltinSchemaType(String schemaTypeOrClassName) {\n        try {\n            return SchemaType.valueOf(schemaTypeOrClassName.toUpperCase());\n        } catch (IllegalArgumentException e) {\n            // schemaType is not referring to builtin type\n            return null;\n        }\n    }","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/ValidatorUtils.java#L31-L67","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n// --schema-type com.acme.MySchema // class missing from jar\n// after\n// add MySchema.class to the function jar, or:\n// --schema-type org.apache.pulsar.common.schema.SchemaType.JSON","handlingStrategy":"validation","validationCode":"// confirm the schema class is loadable before submission\ntry {\n    Class.forName(schemaType);\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Schema class not in jar: \" + schemaType);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ValidatorUtils.validateSchema(schemaType, typeArg, typePool, input);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().endsWith(\"does not exist\")) {\n        // fall back to a built-in schema type or fix the FQCN\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["pulsar-functions","schema","class-not-found","bytebuddy"],"backgroundTag":"class-not-found","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}