apache/pulsar · error · IllegalArgumentException

Source Archive %s does not exist

Error message

Source Archive %s does not exist

What it means

Thrown by validateSourceConfigs in the pulsar-admin CLI when a Source's configured archive is not a supported package URL and does not use the builtin:// scheme, yet no file exists at that path. The CLI must be able to locate the archive containing the Source's code before submitting it, so it verifies the file on local disk. This is a client-side argument validation failure; nothing was sent to the broker.

Source

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

            ObjectMapper mapper = ObjectMapperFactory.getMapper().getObjectMapper();
            TypeReference<HashMap<String, Object>> typeRef = new TypeReference<HashMap<String, Object>>() {};

            return mapper.readValue(str, typeRef);
        }

        protected BatchSourceConfig parseBatchSourceConfigs(String str) {
            return new Gson().fromJson(str, BatchSourceConfig.class);
        }

        protected void validateSourceConfigs(SourceConfig sourceConfig) {
            if (isBlank(sourceConfig.getArchive())) {
                throw new ParameterException("Source archive not specified");
            }
            org.apache.pulsar.common.functions.Utils.inferMissingArguments(sourceConfig);
            if (!Utils.isFunctionPackageUrlSupported(sourceConfig.getArchive())
                    && !sourceConfig.getArchive().startsWith(Utils.BUILTIN)) {
                if (!new File(sourceConfig.getArchive()).exists()) {
                    throw new IllegalArgumentException(String.format("Source Archive %s does not exist",
                            sourceConfig.getArchive()));
                }
            }
            if (isBlank(sourceConfig.getName())) {
                throw new IllegalArgumentException("Source name not specified");
            }

            if (sourceConfig.getBatchSourceConfig() != null) {
                validateBatchSourceConfigs(sourceConfig.getBatchSourceConfig());
            }
        }

        protected void validateBatchSourceConfigs(BatchSourceConfig batchSourceConfig) {
            if (isBlank(batchSourceConfig.getDiscoveryTriggererClassName())) {
                throw new IllegalArgumentException("Discovery Triggerer not specified");
            }
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Verify the file exists: ls the exact path passed to --archive
2. If using a built-in connector, change the archive to builtin://<connector-type> (e.g. builtin://kafka)
3. Use an absolute path instead of a relative one
4. Build the connector NAR first (mvn package) and point --archive at target/...nar

Example fix

// before
--archive ./my-source.nar   (file is actually elsewhere)
// after
--archive /opt/connectors/my-source.nar
// or for built-in:
--archive builtin://kafka

String archive = sourceConfig.getArchive();
if (!org.apache.pulsar.common.functions.Utils.isFunctionPackageUrlSupported(archive)
        && !archive.startsWith(org.apache.pulsar.common.functions.Utils.BUILTIN)
        && !new java.io.File(archive).exists()) {
    throw new IllegalArgumentException("Archive does not exist: " + archive);
}

boolean isValidArchive(String archive) {
    return Utils.isFunctionPackageUrlSupported(archive)
        || archive.startsWith(Utils.BUILTIN)
        || new File(archive).exists();
}

try {
    admin.sources().createSource(sourceConfig);
} catch (IllegalArgumentException e) {
    System.err.println("Check --archive path: " + e.getMessage());
}

When it happens

Trigger: Running `pulsar-admin sources create` (or update/localrun) with --archive pointing to a file path that does not exist, and the path is neither a supported package URL (http(s)://, file:// etc.) nor prefixed with builtin://.

Common situations: Typo in the archive path, running the CLI from a different working directory with a relative path, the nar/jar file not built yet or deleted, or forgetting to prefix with builtin:// when intending to use a bundled connector.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Source name not specified
• Invalid source type '%s' -- Available sources are: %s
• You must specify a name for the source
• Need to provide a persistent topic name
• Need to provide a non-persistent topic name

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