{"record":{"id":"dcece8a3fd4fa5b4","repo":"apache/pulsar","slug":"s-package-does-not-have-the-correct-format-pulsa","errorCode":null,"errorMessage":"%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.","messagePattern":"(.+?) package does not have the correct format\\. Pulsar cannot determine if the package is a NAR package or JAR package\\. (.+?) classname is not provided and attempts to load it as a NAR package produced the following error\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionRuntimeCommon.java","lineNumber":76,"sourceCode":"        Exception jarClassLoaderException = null;\n        Exception narClassLoaderException = null;\n\n        try {\n            try {\n                jarClassLoader = ClassLoaderUtils.extractClassLoader(packageFile);\n            } catch (Exception e) {\n                jarClassLoaderException = e;\n            }\n            try {\n                narClassLoader = extractNarClassLoader(packageFile, narExtractionDirectory);\n            } catch (Exception e) {\n                narClassLoaderException = e;\n            }\n\n            // if connector class name is not provided, we can only try to load archive as a NAR\n            if (isEmpty(connectorClassName)) {\n                if (narClassLoader == null) {\n                    throw new IllegalArgumentException(String.format(\"%s package does not have the correct format. \"\n                                    + \"Pulsar cannot determine if the package is a NAR package or JAR package. \"\n                                    + \"%s classname is not provided and attempts to load it as a NAR package produced \"\n                                    + \"the following error.\",\n                            FunctionCommon.capFirstLetter(componentType), FunctionCommon.capFirstLetter(componentType)),\n                            narClassLoaderException);\n                }\n                try {\n                    if (componentType == FunctionDetails.ComponentType.FUNCTION) {\n                        connectorClassName = FunctionUtils.getFunctionClass(narClassLoader);\n                    } else if (componentType == FunctionDetails.ComponentType.SOURCE) {\n                        connectorClassName = ConnectorUtils.getIOSourceClass(narClassLoader);\n                    } else {\n                        connectorClassName = ConnectorUtils.getIOSinkClass(narClassLoader);\n                    }\n                } catch (IOException e) {\n                    throw new IllegalArgumentException(String.format(\"Failed to extract %s class from archive\",\n                            componentType.toString().toLowerCase()), e);\n                }","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionRuntimeCommon.java#L58-L94","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\n// registering a plain jar without className\nadmin.sources().createSource(sourceConfig, jarPath); // config.className empty\n// after\nsourceConfig.setClassName(\"com.example.MyConnector\");\nadmin.sources().createSource(sourceConfig, jarPath);","handlingStrategy":"try-catch","validationCode":"// Ensure the config carries a class name for non-NAR (jar) packages\nif (config.getClassName() == null || config.getClassName().isEmpty()) {\n    // only acceptable if the archive is a valid NAR\n    try (java.util.jar.JarFile jf = new java.util.jar.JarFile(packagePath)) {\n        // NAR archives contain the pulsar NAR manifest/metadata; absent -> require className\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    getClassLoaderFromPackage(componentType, archivePath, ...);\n} catch (IllegalArgumentException e) {\n    log.error(\"Package {} unusable: provide className or fix NAR layout. Cause: {}\",\n        archivePath, e.getCause() != null ? e.getCause().getMessage() : e.getMessage());\n}","preventionTips":["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."],"tags":["pulsar-functions","nar","classpath","package-format"],"backgroundTag":"invalid-archive-format","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}