apache/pulsar · error · IllegalStateException

Didn't find %s in built-in connectors or functions

Error message

Didn't find %s in built-in connectors or functions

What it means

Thrown by ComponentImpl.getBuiltinArchivePath when a 'builtin://' package path cannot be resolved to any installed archive. The workers' connectors manager and functions manager are both consulted, and if the componentType is null (so neither the connector-specific nor the function-specific message applied), this generic variant is thrown as an IllegalStateException.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/rest/api/ComponentImpl.java:1516

    private Path getBuiltinArchivePath(String pkgPath, FunctionDetails.ComponentType componentType) {
        String type = pkgPath.replaceFirst("^builtin://", "");
        if (!FunctionDetails.ComponentType.FUNCTION.equals(componentType)) {
            Connector connector = worker().getConnectorsManager().getConnector(type);
            if (connector != null) {
                return connector.getArchivePath();
            }
            if (componentType != null) {
                throw new IllegalStateException("Didn't find " + type + " in built-in connectors");
            }
        }
        FunctionArchive function = worker().getFunctionsManager().getFunction(type);
        if (function != null) {
            return function.getArchivePath();
        }
        if (componentType != null) {
            throw new IllegalStateException("Didn't find " + type + " in built-in functions");
        }
        throw new IllegalStateException("Didn't find " + type + " in built-in connectors or functions");
    }

    @Override
    public StreamingOutput downloadFunction(final String path, final AuthenticationParameters authParams) {

        if (!isWorkerServiceAvailable()) {
            throwUnavailableException();
        }

        if (worker().getWorkerConfig().isAuthorizationEnabled()) {
            // to maintain backwards compatibility but still have authorization
            String[] tokens = path.split("/");
            if (tokens.length == 4) {
                String tenant = tokens[0];
                String namespace = tokens[1];
                String componentName = tokens[2];

                throwRestExceptionIfUnauthorizedForNamespace(tenant, namespace, componentName, "download package for",

View on GitHub (pinned to 820761864e)

Solutions

1. Check the exact builtin name against the worker's available connectors/functions (GET /admin/v2/functions/connectors or list the workers' connectors/ functions directories)
2. Place the connector/function NAR file in the worker's configured connectorsDirectory/functionsDirectory and restart the function worker
3. If the archive is not built-in, upload it via package management service or a full URL (http://, file://) instead of builtin://
4. Verify the client is sending the correct componentType so the right registry (connectors vs functions) is consulted

Example fix

// before
String pkgUrl = "builtin://kafka-io"; // connector not installed on worker
// after
// install kafka-connect-nar in $PULSAR_HOME/connectors first, or use the uploaded package URL
String pkgUrl = "builtin://kafka"; // name matching an installed connector archive

String type = pkgPath.replaceFirst("^builtin://", "");
boolean known = admin.functions().getConnectors().stream()
        .anyMatch(c -> c.getName().equals(type) || c.getArchive().contains(type));
if (!known) {
    throw new IllegalArgumentException("builtin archive not installed: " + type);
}

static boolean isBuiltinPackage(String pkgPath) {
    return pkgPath != null && pkgPath.startsWith("builtin://") && pkgPath.length() > "builtin://".length();
}

try {
    streamingOutput.downloadFunction(path, authParams);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("in built-in connectors or functions")) {
        // fall back to uploading the archive or fixing the builtin name
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling getFunction/getSink/getSource download or submission APIs with a package path like 'builtin://my-connector' where the connector name does not exist in the worker's connectors list AND the name does not match any registered built-in function archive, with componentType null (unknown component type).

Common situations: Typo in the builtin:// name; using a connector that was never placed in the worker's connectors directory; worker config missing the connector/function NAR at startup; upgrading Pulsar where a previously built-in connector was removed; client sending builtin:// URL without specifying the component type.

Related errors

• Built-in ${componentType} is not available
• Unknown component type: %s
• Access to environment variable %s is not allowed.
• PulsarAdmin is not enabled in function worker
• Getting consumer is not supported

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