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. Attempts to load it as a NAR package produced error:

What it means

When a connector class name is provided but the archive could not be loaded as either a JAR or a NAR, getClassLoaderFromPackage builds this message explaining Pulsar cannot determine the package format, appending any NAR-loading error message.

Source

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

                    }
                } else {
                    StringBuilder errorMsg = new StringBuilder(FunctionCommon.capFirstLetter(componentType)
                            + " package does not have the correct format."
                            + " Pulsar cannot determine if the package is a NAR package or JAR package.");

                    if (jarClassLoaderException != null) {
                        errorMsg.append(
                                " Attempts to load it as a JAR package produced error: " + jarClassLoaderException
                                        .getMessage());
                    }

                    if (narClassLoaderException != null) {
                        errorMsg.append(
                                " Attempts to load it as a NAR package produced error: " + narClassLoaderException
                                        .getMessage());
                    }

                    throw new IllegalArgumentException(errorMsg.toString());
                }
            }
        } finally {
            if (!keepJarClassLoader) {
                ClassLoaderUtils.closeClassLoader(jarClassLoader);
            }
            if (!keepNarClassLoader) {
                ClassLoaderUtils.closeClassLoader(narClassLoader);
            }
        }
    }

}

View on GitHub (pinned to 820761864e)

Solutions

Run 'file my-archive.jar' and 'unzip -t my-archive.jar' to confirm it is a valid ZIP/JAR
Re-download/re-upload the archive — a truncated transfer is the most common cause
If it should be a NAR, verify it has the correct structure (META-INF/MANIFEST.MF, shaded dependencies)
Read the appended 'error: ...' text in the message — it names the actual NAR loading problem

Example fix

// before
curl -o connector.nar https://mirror/connector.nar  # interrupted download
// after
curl -fSL -o connector.nar https://mirror/connector.nar && unzip -t connector.nar

Defensive patterns

Strategy: validation

Validate before calling

// check the archive is a valid ZIP before submitting
try (ZipFile zf = new ZipFile(archive.toFile())) {
  if (zf.getEntry("META-INF/MANIFEST.MF") == null) {
    throw new IllegalStateException("Not a valid JAR/NAR: missing manifest");
  }
}

Try / catch

try {
  createFunction(...);
} catch (IllegalArgumentException e) {
  // message includes the NAR-loading error after "produced error: "
  log.error("Archive format invalid: {}", e.getMessage());
}

Prevention

Verify integrity after download (checksum or 'unzip -t')
Ensure the correct file is uploaded (a real JAR/NAR, not a redirect page or tarball)
Build NARs with the official pulsar NAR layout so both JAR and NAR loading paths behave predictably

When it happens

Trigger: Registering a source/sink with an explicit class name where both jar creation and NAR creation of the archive failed (e.g. invalid ZIP structure, missing NAR manifest, corrupt upload).

Common situations: Uploaded a wrong file (e.g. a tar.gz, a pom.xml, an HTML error page saved as .jar); truncated download; NAR missing the required manifest/structure while also being unloadable as a plain jar.

Related errors

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