apache/pulsar · error · IllegalArgumentException

%s package does not have the correct format. Pulsar cannot d

Error message

%s package does not have the correct format. Pulsar cannot determine if the package is a NAR package or JAR package. %s classname is not provided and attempts to load it as a NAR package produced the following error.

What it means

getClassLoaderFromPackage first tries loading the archive as a NAR, then (if a connector class name is given) as a JAR. When no connector class name is provided and the NAR attempt failed, it cannot decide the package type and throws IllegalArgumentException wrapping the original NAR exception.

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionRuntimeCommon.java:76

        Exception jarClassLoaderException = null;
        Exception narClassLoaderException = null;

        try {
            try {
                jarClassLoader = ClassLoaderUtils.extractClassLoader(packageFile);
            } catch (Exception e) {
                jarClassLoaderException = e;
            }
            try {
                narClassLoader = extractNarClassLoader(packageFile, narExtractionDirectory);
            } catch (Exception e) {
                narClassLoaderException = e;
            }

            // if connector class name is not provided, we can only try to load archive as a NAR
            if (isEmpty(connectorClassName)) {
                if (narClassLoader == null) {
                    throw new IllegalArgumentException(String.format("%s package does not have the correct format. "
                                    + "Pulsar cannot determine if the package is a NAR package or JAR package. "
                                    + "%s classname is not provided and attempts to load it as a NAR package produced "
                                    + "the following error.",
                            FunctionCommon.capFirstLetter(componentType), FunctionCommon.capFirstLetter(componentType)),
                            narClassLoaderException);
                }
                try {
                    if (componentType == FunctionDetails.ComponentType.FUNCTION) {
                        connectorClassName = FunctionUtils.getFunctionClass(narClassLoader);
                    } else if (componentType == FunctionDetails.ComponentType.SOURCE) {
                        connectorClassName = ConnectorUtils.getIOSourceClass(narClassLoader);
                    } else {
                        connectorClassName = ConnectorUtils.getIOSinkClass(narClassLoader);
                    }
                } catch (IOException e) {
                    throw new IllegalArgumentException(String.format("Failed to extract %s class from archive",
                            componentType.toString().toLowerCase()), e);
                }

View on GitHub (pinned to 820761864e)

Solutions

Provide the connector class name (className) so the loader can try the JAR path.
Verify the package really is a NAR (correct manifest/descriptor) or repackage it with the proper NAR layout.
Re-upload the package — the wrapped narClassLoaderException cause may show a corrupt/missing archive.
Use the correct package type (built-in vs uploaded) for the component being registered.

Example fix

// before
// registering a plain jar without className
admin.sources().createSource(sourceConfig, jarPath); // config.className empty
// after
sourceConfig.setClassName("com.example.MyConnector");
admin.sources().createSource(sourceConfig, jarPath);

Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure the config carries a class name for non-NAR (jar) packages
if (config.getClassName() == null || config.getClassName().isEmpty()) {
    // only acceptable if the archive is a valid NAR
    try (java.util.jar.JarFile jf = new java.util.jar.JarFile(packagePath)) {
        // NAR archives contain the pulsar NAR manifest/metadata; absent -> require className
    }
}

Try / catch

try {
    getClassLoaderFromPackage(componentType, archivePath, ...);
} catch (IllegalArgumentException e) {
    log.error("Package {} unusable: provide className or fix NAR layout. Cause: {}",
        archivePath, e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
}

Prevention

Always set the connector/function class name when uploading plain jars.
Verify packages are valid NARs (correct manifest/descriptor) before registration.
Check the wrapped cause exception for the real NAR load failure.
Re-upload corrupted or partially transferred archives.

When it happens

Trigger: Registering/updating a connector or component whose package is neither a valid NAR nor resolvable: connectorClassName is empty and NarClassLoader construction failed (bad archive layout, missing nar metadata).

Common situations: Uploading a plain jar without specifying the class name; a jar mislabeled .nar missing the NAR manifest/descriptor; corrupted or partially uploaded package; wrong package type selected for the component.

Related errors

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