What causes "Could not find built in archive definition" in apache/pulsar?

Correct the builtin name in the function config to match a NAR present in the worker's functions directory

apache/pulsar · error · IOException

Could not find built in archive definition

Error message

Could not find built in archive definition

What it means

FunctionActioner.getBuiltinArchive resolves the local NAR archive of a built-in connector/function via the FunctionsManager. If the component is not a built-in function, or the builtin name has no registered archive, an IOException 'Could not find built in archive definition' is thrown.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionActioner.java:588

            SinkSpec sinkSpec = functionDetails.getSink();
            if (!StringUtils.isEmpty(sinkSpec.getBuiltin())) {
                Connector connector = connectorsManager.getConnector(sinkSpec.getBuiltin());

                File archive = connector.getArchivePath().toFile();
                String sinkClass = connector.getConnectorDefinition().getSinkClass();
                functionDetails.getSink().setClassName(sinkClass);

                fillSinkTypeClass(functionDetails, connector.getConnectorFunctionPackage(), sinkClass);
                return archive;
            }
        }

        if (componentType == FunctionDetails.ComponentType.FUNCTION
                && !StringUtils.isEmpty(functionDetails.getBuiltin())) {
            return functionsManager.getFunctionArchive(functionDetails.getBuiltin()).toFile();
        }

        throw new IOException("Could not find built in archive definition");
    }

    private void fillSourceTypeClass(FunctionDetails functionDetails,
                                     ValidatableFunctionPackage functionPackage, String className) {
        String typeArg = getSourceType(className, functionPackage.getTypePool()).asErasure().getName();

        functionDetails.getSource().setTypeClassName(typeArg);

        if (!functionDetails.hasSink() || StringUtils.isEmpty(functionDetails.getSink().getTypeClassName())) {
            functionDetails.setSink().setTypeClassName(typeArg);
        }
    }

    private void fillSinkTypeClass(FunctionDetails functionDetails,
                                   ValidatableFunctionPackage functionPackage, String className) {
        String typeArg = getSinkType(className, functionPackage.getTypePool()).asErasure().getName();

        functionDetails.getSink().setTypeClassName(typeArg);

View on GitHub (pinned to 820761864e)

Solutions

Correct the builtin name in the function config to match a NAR present in the worker's functions directory
Deploy/copy the required builtin NAR archive to the worker's connector/functions directory and restart the worker
Use an explicit user-code package URL instead of builtin if no built-in archive exists

Example fix

// before
.setBuiltin("kafk-source") // typo, archive not found
// after
.setBuiltin("kafka")

Defensive patterns

Strategy: try-catch

Validate before calling

String builtin = functionDetails.getBuiltin();
Path narDir = Paths.get(workerConfig.getFunctionsDirectory());
boolean exists = builtin != null && java.util.Arrays.stream(narDir.toFile().listFiles())
    .anyMatch(f -> f.getName().contains(builtin));
if (!exists) throw new IllegalStateException("builtin archive missing: " + builtin);

Try / catch

try {
    functionActioner.startFunction(...);
} catch (IOException e) {
    if (e.getMessage().contains("Could not find built in archive definition")) {
        // deploy the NAR to the worker functions directory or fix builtin name
    } else { throw e; }
}

Prevention

List available builtins with pulsar-admin functions before referencing one
Ensure every worker host has the same set of builtin NARs deployed
Spell-check builtin names; they must match the NAR-defined connector name exactly

When it happens

Trigger: pkgFile resolution for a function whose FunctionDetails declares a builtin name that is not found in the worker's functionsManager, or a non-FUNCTION component reaching this path.

Common situations: Misspelled builtin connector name in function config; builtin NAR missing from the worker's functions directory; using a source/sink builtin with a code path expecting FUNCTION type.

Related errors

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