apache/pulsar · error · IllegalArgumentException

Built-in ${componentType} is not available

Error message

Built-in ${componentType} is not available

What it means

This IllegalArgumentException is thrown by ComponentImpl when resolving a component archive URL that starts with the builtin:// scheme. The worker looks up the archive name in its configured functions/IO connector registry (getFunction); if no built-in connector or function with that name is installed on the worker, registration fails with this message. It means the referenced built-in archive does not exist on this worker's nar extraction/conf directory.

Source

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

            try {
                return FunctionCommon.extractFileFromPkgURL(functionPkgUrl);
            } catch (Exception e) {
                throw new IllegalArgumentException(String.format("Encountered error \"%s\" "
                                + "when getting %s package from %s", e.getMessage(),
                        ComponentTypeUtils.toString(componentType), functionPkgUrl), e);
            }
        }
    }

    protected ValidatableFunctionPackage getBuiltinFunctionPackage(String archive) {
        if (!StringUtils.isEmpty(archive)) {
            if (archive.startsWith(org.apache.pulsar.common.functions.Utils.BUILTIN)) {
                archive = archive.replaceFirst("^builtin://", "");

                FunctionArchive function = worker().getFunctionsManager().getFunction(archive);
                // check if builtin connector exists
                if (function == null) {
                    throw new IllegalArgumentException("Built-in " + componentType + " is not available");
                }
                return function.getFunctionPackage();
            }
        }
        return null;
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Verify the exact built-in name with 'pulsar-admin functions list-builtins' (or sources/sinks equivalents) and correct the archive string
2. Install the connector NAR into the worker's functions/connector directory and restart the functions worker
3. If the package is custom, upload the actual jar via --jar instead of using builtin://

Example fix

// before
config.setArchive("builtin://data-generater");
// after
config.setArchive("builtin://data-generator");

String archive = cfg.getArchive();
if (archive != null && archive.startsWith("builtin://")) {
    String name = archive.replaceFirst("^builtin://", "");
    java.util.Set<String> builtins = admin.functions().getBuiltInFunctions() != null
        ? admin.functions().getBuiltInFunctions() : java.util.Collections.emptySet();
    if (!builtins.contains(name)) throw new IllegalStateException("Built-in not installed: " + name);
}

boolean isValidBuiltin(String archive, java.util.Set<String> installed) {
    return archive != null && (!archive.startsWith("builtin://")
        || installed.contains(archive.replaceFirst("^builtin://", "")));
}

try { admin.functions().createFunction(...); }
catch (org.apache.pulsar.client.admin.PulsarAdminException e) {
    if (String.valueOf(e.getMessage()).contains("is not available")) {
        // verify installed built-ins and retry with corrected archive
    }
}

When it happens

Trigger: Registering or updating a function/sink/source with functionConfig or archive set to 'builtin://<name>' where <name> is not present in the worker's configured connector/sink/source archives (workerConfig functions/connector/sink directories or the functions worker's built-in list).

Common situations: Typo in the built-in connector name (e.g. builtin://data-generator vs builtin://pubsub); deploying to a cluster whose worker does not ship the connector NAR; connector added after worker startup; case-sensitivity mismatch in the archive name.

Related errors

• Didn't find %s in built-in connectors or functions
• 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/643bfa3bb8884be0. Report an issue: GitHub.