microsoft/semantic-kernel · error · KernelException

Invalid argument type for function {functionMetadata.Name}.

Error message

Invalid argument type for function {functionMetadata.Name}. Parameter {param.Name} expects type {param.ParameterType ?? (object?)param.Schema} but received {value?.GetType().ToString() ?? "<null>"}.

What it means

Thrown during hash-argument processing when a provided argument value's type does not match the expected parameter type. The helper validates each supplied argument against the function metadata before invoking the kernel function.

Source

Thrown at dotnet/src/Extensions/PromptTemplates.Handlebars/Helpers/KernelHelpers/KernelFunctionHelpers.cs:154

        KernelFunctionMetadata functionMetadata,
        KernelArguments executionContext,
        IDictionary<string, object>? handlebarsArguments,
        string nameDelimiter)
    {
        // Prepare the input parameters for the function
        foreach (var param in functionMetadata.Parameters)
        {
            var fullyQualifiedParamName = functionMetadata.Name + nameDelimiter + param.Name;
            if (handlebarsArguments is not null && (handlebarsArguments.TryGetValue(fullyQualifiedParamName, out var value) || handlebarsArguments.TryGetValue(param.Name, out value)))
            {
                value = KernelHelpersUtils.GetArgumentValue(value, executionContext);
                if (IsExpectedParameterType(param, value))
                {
                    executionContext[param.Name] = value;
                }
                else
                {
                    throw new KernelException($"Invalid argument type for function {functionMetadata.Name}. Parameter {param.Name} expects type {param.ParameterType ?? (object?)param.Schema} but received {value?.GetType().ToString() ?? "<null>"}.");
                }
            }
            else if (param.IsRequired)
            {
                throw new KernelException($"Parameter {param.Name} is required for function {functionMetadata.Name}.");
            }
        }
    }

    /// <summary>
    /// Processes the positional arguments passed to a Handlebars helper function.
    /// </summary>
    /// <param name="functionMetadata">KernelFunctionMetadata for the function being invoked.</param>
    /// <param name="executionContext">Arguments maintained in the executing context.</param>
    /// <param name="handlebarsArguments">Arguments passed to the Handlebars helper.</param>
    /// <exception cref="KernelException">Thrown when a required parameter is missing.</exception>
    private static void ProcessPositionalArguments(KernelFunctionMetadata functionMetadata, KernelArguments executionContext, Arguments handlebarsArguments)
    {

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Align the argument value type in the template with the parameter's declared type (e.g., pass numeric literals for int parameters).
2. Pre-validate kernel argument values before rendering the template.
3. Update the function metadata schema if the parameter type changed and templates must adapt.

Example fix

// before (param expects int)
{{Plugin-Function count="3"}}
// after
{{Plugin-Function count=3}}

foreach (var param in functionMetadata.Parameters)
{
    if (handlebarsArguments.TryGetValue(param.Name, out var value) && !IsExpectedParameterType(param, value))
        throw new InvalidOperationException($"Argument '{param.Name}' type mismatch for {functionMetadata.Name}.");
}

// Reuse the library's own check if exposed; otherwise mirror parameter type expectations
public static bool MatchesParamType(KernelParameterMetadata param, object? value)
{
    if (param.ParameterType is null) return true;
    return value is null ? !param.IsRequired : param.ParameterType.IsAssignableFrom(value.GetType());
}

try
{
    var result = await template.RenderAsync(kernel, arguments).ConfigureAwait(false);
}
catch (KernelException ex) when (ex.Message.Contains("Invalid argument type"))
{
    _logger.LogError(ex, "Hash argument type mismatch; convert the value to the declared type.");
    throw;
}

When it happens

Trigger: ProcessHashArguments checks IsExpectedParameterType(param, value) for each hash-supplied argument; a type mismatch (e.g., passing a string where an int is expected, or null for a non-nullable) throws this.

Common situations: Template supplies a literal of the wrong type (e.g., {{Function count="three"}} for an int parameter), a variable resolves to an unexpected runtime type, or schema/parameter type changes between versions.

Related errors

• Parameter {param.Name} is required for function {functionMet
• Invalid parameter type for function {functionMetadata.Name}.
• No arguments are provided for {fullyResolvedFunctionName}.
• Invalid parameter count for function {functionMetadata.Name}
• Argument '{propertyName}' has a value that doesn't support a

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