apache/pulsar · error · IllegalStateException

The archive property must be specified in SourceConfig./Sink

Error message

The archive property must be specified in SourceConfig./SinkConfig.

What it means

For Source or Sink components, LocalRunner requires the archive property to be set (sources/sinks are always loaded from an archive/NAR). extractClassLoader throws IllegalStateException '<archive property must be specified in SourceConfig./SinkConfig.>' when it is missing.

Source

Thrown at pulsar-functions/localrun/src/main/java/org/apache/pulsar/functions/LocalRunner.java:534

                        componentType, className, file, narExtractionDirectory);
                classLoaderCreated = true;
            } else {
                if (!(runtimeEnv == null || runtimeEnv == RuntimeEnv.THREAD)) {
                    String errorMsg;
                    switch (componentType) {
                        case FUNCTION:
                            errorMsg = "The jar property must be specified in FunctionConfig.";
                            break;
                        case SOURCE:
                            errorMsg = "The archive property must be specified in SourceConfig.";
                            break;
                        case SINK:
                            errorMsg = "The archive property must be specified in SinkConfig.";
                            break;
                        default:
                            throw new IllegalStateException("Unexpected ComponentType: " + componentType);
                    }
                    throw new IllegalStateException(errorMsg);
                }
            }
        }
        return new UserCodeClassLoader(classLoader, classLoaderCreated);
    }

    private void startProcessMode(FunctionDetails functionDetails,
                                           int parallelism, int instanceIdOffset, String serviceUrl,
                                           String stateStorageServiceUrl, AuthenticationConfig authConfig,
                                           String userCodeFile, String transformFunctionFile) throws Exception {
        SecretsProviderConfigurator secretsProviderConfigurator = getSecretsProviderConfigurator();
        runtimeFactory = new ProcessRuntimeFactory(
                serviceUrl,
                webServiceUrl,
                stateStorageServiceUrl,
                authConfig,
                null, /* java instance jar file */
                null, /* python instance file */

View on GitHub (pinned to 820761864e)

Solutions

1. Call setArchive("/absolute/path/to/built-nar-or-jar") on the SourceConfig/SinkConfig
2. Verify the config instance passed to LocalRunner is the one carrying the archive
3. For builtin connectors use the builtin: prefix if your setup supports it, otherwise always supply an archive

Example fix

// before
SinkConfig sinkConfig = new SinkConfig();
sinkConfig.setClassName("org.example.MySink");
// after
SinkConfig sinkConfig = new SinkConfig();
sinkConfig.setClassName("org.example.MySink");
sinkConfig.setArchive("/path/to/pulsar-io-my-sink.nar");

if ((config instanceof SourceConfig && ((SourceConfig) config).getArchive() == null)
        || (config instanceof SinkConfig && ((SinkConfig) config).getArchive() == null)) {
    throw new IllegalStateException("archive is required for source/sink configs");
}

try {
    runner.start(true);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("archive property must be specified")) {
        // set archive and restart with a fresh runner
    }
}

When it happens

Trigger: Building a SourceConfig or SinkConfig without calling setArchive(...) and then starting LocalRunner; archive null-ed by later code paths.

Common situations: Copied function examples (functions don't need an archive) adapted to sources/sinks without setting archive; programmatically constructed source/sink configs missing the field.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Timeout during delete operation
• Timeout during close operation
• Timeout during open-cursor operation
• Timeout during delete-cursors operation
• Timeout during managed ledger terminate

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