microsoft/semantic-kernel · error · HandlebarsRuntimeException

`json` helper requires a value to be passed in.

Error message

`json` helper requires a value to be passed in.

What it means

Thrown by the Handlebars `json` helper when it is invoked with zero arguments (`arguments.Length == 0`). The helper serializes a value to JSON (or passes strings through); with no value to serialize there is nothing meaningful to produce, so it aborts at render time.

Source

Thrown at dotnet/src/Extensions/PromptTemplates.Handlebars/Helpers/KernelHelpers/KernelSystemHelpers.cs:94

                name = (string)parameters!["name"];
                value = GetArgumentValue(parameters!["value"], variables);
            }
            else
            {
                var args = ProcessArguments(arguments, variables);
                name = args[0].ToString() ?? string.Empty;
                value = args[1];
            }

            // Set the variable in the Handlebars context
            variables[name] = value;
        });

        handlebarsInstance.RegisterHelper("json", (in HelperOptions options, in Context context, in Arguments arguments) =>
        {
            if (arguments.Length == 0)
            {
                throw new HandlebarsRuntimeException("`json` helper requires a value to be passed in.");
            }

            var args = ProcessArguments(arguments, variables);
            object objectToSerialize = args[0];

            object v = objectToSerialize switch
            {
                string stringObject => objectToSerialize,
                _ => JsonSerializer.Serialize(objectToSerialize, s_jsonSerializerOptions)
            };

            return v;
        });

        handlebarsInstance.RegisterHelper("concat", (in HelperOptions options, in Context context, in Arguments arguments) =>
        {
            var args = ProcessArguments(arguments, variables);
            return string.Concat(args);

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass the value explicitly: `{{json myValue}}`.
2. Confirm the variable is actually populated in KernelArguments before render — absent variables are not passed as arguments.
3. If the value is optional, guard it with an `{{#if myValue}}...{{json myValue}}...{{/if}}` block.

Example fix

// before
{{json}}
// after
{{json userPreferences}}

// Ensure the variable exists in KernelArguments before render:
if (!arguments.Contains("myValue")) {
    throw new InvalidOperationException("myValue is required for the json helper.");
}

When it happens

Trigger: Writing `{{json}}` with no argument, or `{{json undefinedVariable}}` where the variable resolved to nothing and was dropped by Handlebars argument binding.

Common situations: Forgetting to supply the variable name; referencing a variable that was never added to KernelArguments so it is absent rather than null; copy-pasting a template snippet and leaving the value off.

Related errors

• Message must have a role.
• Unable to restore channel: invalid state.
• Unable to transform output to {typeof(TOutput)}.
• Unable to transform result into {typeof(TOutput).Name}
• Unexpected author role: {role}

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/5b5c5f5a9c1d65c6. Report an issue: GitHub.