apache/pulsar · error · ParameterException

--source-file needs to be specified

Error message

--source-file needs to be specified

What it means

Thrown by the `functions upload` subcommand when --source-file is blank. Uploading a function artifact to Pulsar's package management requires a local source file to send to the service via functions().uploadFunction.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdFunctions.java:1179

                description = "The file whose contents need to be uploaded")
        protected String sourceFile;
        @Option(
                names = "--path",
                description = "Path or functionPkgUrl where the contents need to be stored", required = true)
        protected String path;

        private void mergeArgs() {
            if (isBlank(sourceFile) && !isBlank(deprecatedSourceFile)) {
                sourceFile = deprecatedSourceFile;
            }
        }

        @Override
        void runCmd() throws Exception {
            // merge deprecated args with new args
            mergeArgs();
            if (StringUtils.isBlank(sourceFile)) {
                throw new ParameterException("--source-file needs to be specified");
            }
            getAdmin().functions().uploadFunction(sourceFile, path);
            print("Uploaded successfully");
        }
    }

    @Command(description = "Download File Data from Pulsar")
    class DownloadFunction extends FunctionCommand {
        // for backward compatibility purposes
        @Option(
                names = "--destinationFile",
                description = "The file to store downloaded content", hidden = true)
        protected String deprecatedDestinationFile;
        @Option(
                names = "--destination-file",
                description = "The file to store downloaded content")
        protected String destinationFile;
        @Option(

View on GitHub (pinned to 820761864e)

Solutions

1. Add --source-file <localArtifactPath> pointing at the jar/py/binary to upload
2. Verify the artifact path variable is non-empty in scripts
3. Keep --path (the remote destination) together with --source-file

Example fix

// before
pulsar-admin functions upload --path myfunc/myfunc.jar
// after
pulsar-admin functions upload --source-file ./target/myfunc.jar --path myfunc/myfunc.jar

if (sourceFile == null || sourceFile.isBlank()) {
    throw new IllegalArgumentException("--source-file is required for functions upload");
}
if (!new File(sourceFile).exists()) {
    throw new IllegalArgumentException("source file does not exist: " + sourceFile);
}

try { admin.functions().uploadFunction(sourceFile, path); }
catch (ParameterException e) { if (e.getMessage().contains("--source-file")) { log.error("Provide --source-file <local artifact>"); } throw e; }

When it happens

Trigger: Running `pulsar-admin functions upload --path <destination>` without --source-file (or with an empty value), checked at CmdFunctions.java:1179.

Common situations: Uploading to a package path but forgetting the local artifact flag; script variable pointing at the artifact was empty; confusing upload with download argument names (--source-file is upload-only).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Either a Java jar or a Python file or a Go executable binary
• Either a Java jar or a Python file or a Go executable binary
• Function Name not provided
• State key needs to be specified
• Either a trigger value or a trigger filepath needs to be spe

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