What causes "Failed to resolve type for Source class %s" in apache/pulsar?

Ensure the source class exists in the uploaded archive and all its dependencies are packaged

apache/pulsar · error · IllegalArgumentException

Failed to resolve type for Source class %s

Error message

Failed to resolve type for Source class %s

What it means

The framework attempts to reflectively determine the record type (type argument) of the Source class via getSourceType. If that reflective resolution fails (class not loadable, no resolvable type argument, linkage errors), it is rethrown as an IllegalArgumentException with this message.

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/SourceConfigUtils.java:337

        }

        if (sourceClass.asErasure().isAssignableTo(BatchSource.class)) {
            if (sourceConfig.getBatchSourceConfig() != null) {
                validateBatchSourceConfig(sourceConfig.getBatchSourceConfig());
            } else {
                throw new IllegalArgumentException(
                  String.format("Source class %s implements %s but batch source source config is not specified",
                    sourceClass.getName(), BatchSource.class.getName()));
            }
        }

        // extract type from source class
        TypeDefinition typeArg;

        try {
            typeArg = getSourceType(sourceClass);
        } catch (Exception e) {
            throw new IllegalArgumentException(
                    String.format("Failed to resolve type for Source class %s", sourceClassName), e);
        }

        // Only one of serdeClassName or schemaType should be set
        if (!StringUtils.isEmpty(sourceConfig.getSerdeClassName()) && !StringUtils
                .isEmpty(sourceConfig.getSchemaType())) {
            throw new IllegalArgumentException("Only one of serdeClassName or schemaType should be set");
        }

        if (!StringUtils.isEmpty(sourceConfig.getSerdeClassName())) {
            ValidatorUtils.validateSerde(sourceConfig.getSerdeClassName(), typeArg, sourceFunction.getTypePool(),
                    false);
        }
        if (!StringUtils.isEmpty(sourceConfig.getSchemaType())) {
            ValidatorUtils.validateSchema(sourceConfig.getSchemaType(), typeArg, sourceFunction.getTypePool(),
                    false);
        }

View on GitHub (pinned to 820761864e)

Solutions

Ensure the source class exists in the uploaded archive and all its dependencies are packaged
Declare the source class with an explicit concrete type argument, e.g. implements Source<String>
Verify className in SourceConfig matches the fully qualified class name inside the archive
Rebuild/re-upload the connector NAR or function package and retry

Example fix

// before
public class MySource implements Source { ... }
// after
public class MySource implements Source<String> { ... }

Defensive patterns

Strategy: try-catch

Validate before calling

try {
    Class<?> c = loader.loadClass(config.getClassName());
    if (!Source.class.isAssignableFrom(c)) throw new IllegalArgumentException("not a Source");
} catch (ClassNotFoundException e) {
    throw new IllegalArgumentException("Source class not in archive: " + config.getClassName());
}

Try / catch

try { validateAndExtractDetails(...); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Failed to resolve type for Source class")) { log.error("Check archive contents and generic type declaration", e); } else { throw e; } }

Prevention

Declare concrete generic type args on Source implementations (Source<T>, not raw Source)
Package all dependencies in the function/connector archive
Match className exactly with the class inside the uploaded NAR/JAR
Smoke-test the archive by loading the class locally before upload

When it happens

Trigger: validateAndExtractDetails calls getSourceType(sourceClass) and it throws any Exception — e.g. the class cannot be loaded from the uploaded archive or its generic Source<T> type argument cannot be resolved.

Common situations: Source class missing from the uploaded function/connector archive; class has dependencies not packaged; source class implements raw Source without a type parameter or uses generics that reflection cannot resolve; wrong archive uploaded for the declared className.

Related errors

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