{"record":{"id":"df15c936ec4c1822","repo":"microsoft/garnet","slug":"could-not-run-function-preamble-errmsg","errorCode":null,"errorMessage":"Could not run function preamble: {errMsg}","messagePattern":"Could not run function preamble: (.+?)","errorType":"exception","errorClass":"GarnetException","httpStatus":null,"severity":"error","filePath":"libs/server/Lua/LuaRunner.cs","lineNumber":1226,"sourceCode":"                    preambleArgv = argv;\n\n                    state.PushCFunction(&LuaRunnerTrampolines.RunPreambleForRunner);\n                    var preambleRes = state.PCall(0, 0);\n                    if (preambleRes != LuaStatus.OK || state.StackTop != 0)\n                    {\n                        string errMsg;\n                        if (state.StackTop >= 1 && state.Type(1) == LuaType.String)\n                        {\n                            // We control the definition of LoaderBlock, so we know this is a string\n                            state.KnownStringToBuffer(1, out var preambleErrSpan);\n                            errMsg = Encoding.UTF8.GetString(preambleErrSpan);\n                        }\n                        else\n                        {\n                            errMsg = \"No error provided\";\n                        }\n\n                        throw new GarnetException($\"Could not run function preamble: {errMsg}\");\n                    }\n                }\n                finally\n                {\n                    preambleKeys = preambleArgv = null;\n                }\n\n                RunnerAdapter adapter;\n                if (txnMode && keys?.Length > 0)\n                {\n                    // Add keys to the transaction\n                    foreach (var key in keys)\n                    {\n                        var _key = scratchBufferBuilder.CreateArgSlice(key);\n                        txnKeyEntries.AddKey(_key, Tsavorite.core.LockType.Exclusive);\n                        scratchBufferBuilder.RewindScratchBuffer(_key);\n                    }\n","sourceCodeStart":1208,"sourceCodeEnd":1244,"githubUrl":"https://github.com/microsoft/garnet/blob/951b0fc6838721f89d102c2bbe1b914e8d39d700/libs/server/Lua/LuaRunner.cs#L1208-L1244","documentation":"Thrown when executing a registered function (e.g., FCALL) and the function's preamble - the code that registers declared keys and argv into the sandbox - fails its protected call. errMsg is the Lua error from the stack (or 'No error provided' if the stack was empty). The preamble is built by Garnet from the function's key_specs, so a failure usually means a malformed function registration or a bad key declaration.","triggerScenarios":"An FCALL/FCALL_RO invocation runs state.PushCFunction(RunPreambleForRunner) then PCall; it returns non-OK or leaves items on the stack, so the preamble did not complete cleanly.","commonSituations":"A function declared with an invalid number-of-keys spec; a function whose preamble references a removed/disallowed API; mismatch between registered function metadata and the runtime.","solutions":["Re-examine the function's key-count/key declaration at registration time.","Read errMsg for the Lua-side cause.","Reload the function with corrected metadata."],"exampleFix":"-- before (Lua) - wrong key count declared\nredis.register_function { function_name='f', key_count=5, callback=cb }  -- only passes 2 keys\n-- after\nredis.register_function { function_name='f', key_count=2, callback=cb }","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    result = server.FCall(\"f\", keys, argv);\n} catch (GarnetException ex) when (ex.Message.StartsWith(\"Could not run function preamble\")) {\n    logger.LogError(\"Function preamble failed: {Msg}\", ex.Message);\n    return ServiceUnavailable(ex.Message);\n}","preventionTips":["Validate key-count metadata against actual call arguments before FCALL.","Register and smoke-test functions right after FUNCTION LOAD to catch preamble errors early."],"tags":["lua","scripting","function","preamble"],"backgroundTag":null,"analyzedSha":"951b0fc6838721f89d102c2bbe1b914e8d39d700","analyzedAt":"2026-08-13T19:01:32.939Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}