{"record":{"id":"3c61eca9c546ca2e","repo":"apache/pulsar","slug":"could-not-find-built-in-archive-definition","errorCode":null,"errorMessage":"Could not find built in archive definition","messagePattern":"Could not find built in archive definition","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionActioner.java","lineNumber":588,"sourceCode":"            SinkSpec sinkSpec = functionDetails.getSink();\n            if (!StringUtils.isEmpty(sinkSpec.getBuiltin())) {\n                Connector connector = connectorsManager.getConnector(sinkSpec.getBuiltin());\n\n                File archive = connector.getArchivePath().toFile();\n                String sinkClass = connector.getConnectorDefinition().getSinkClass();\n                functionDetails.getSink().setClassName(sinkClass);\n\n                fillSinkTypeClass(functionDetails, connector.getConnectorFunctionPackage(), sinkClass);\n                return archive;\n            }\n        }\n\n        if (componentType == FunctionDetails.ComponentType.FUNCTION\n                && !StringUtils.isEmpty(functionDetails.getBuiltin())) {\n            return functionsManager.getFunctionArchive(functionDetails.getBuiltin()).toFile();\n        }\n\n        throw new IOException(\"Could not find built in archive definition\");\n    }\n\n    private void fillSourceTypeClass(FunctionDetails functionDetails,\n                                     ValidatableFunctionPackage functionPackage, String className) {\n        String typeArg = getSourceType(className, functionPackage.getTypePool()).asErasure().getName();\n\n        functionDetails.getSource().setTypeClassName(typeArg);\n\n        if (!functionDetails.hasSink() || StringUtils.isEmpty(functionDetails.getSink().getTypeClassName())) {\n            functionDetails.setSink().setTypeClassName(typeArg);\n        }\n    }\n\n    private void fillSinkTypeClass(FunctionDetails functionDetails,\n                                   ValidatableFunctionPackage functionPackage, String className) {\n        String typeArg = getSinkType(className, functionPackage.getTypePool()).asErasure().getName();\n\n        functionDetails.getSink().setTypeClassName(typeArg);","sourceCodeStart":570,"sourceCodeEnd":606,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionActioner.java#L570-L606","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n.setBuiltin(\"kafk-source\") // typo, archive not found\n// after\n.setBuiltin(\"kafka\")","handlingStrategy":"try-catch","validationCode":"String builtin = functionDetails.getBuiltin();\nPath narDir = Paths.get(workerConfig.getFunctionsDirectory());\nboolean exists = builtin != null && java.util.Arrays.stream(narDir.toFile().listFiles())\n    .anyMatch(f -> f.getName().contains(builtin));\nif (!exists) throw new IllegalStateException(\"builtin archive missing: \" + builtin);","typeGuard":null,"tryCatchPattern":"try {\n    functionActioner.startFunction(...);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"Could not find built in archive definition\")) {\n        // deploy the NAR to the worker functions directory or fix builtin name\n    } else { throw e; }\n}","preventionTips":["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"],"tags":["pulsar-functions","worker","builtin","nar","archive-not-found"],"backgroundTag":"builtin-archive-not-found","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}