microsoft/aspire · error · PolyglotCapabilityInvocationException

TYPE_MISMATCH

TYPE_MISMATCH

Error message

Could not invoke '{methodName}': {scrubbedMessage}

What it means

When a registered capability method invocation fails with an ArgumentException classified as a type mismatch, the dispatcher converts it into a TYPE_MISMATCH PolyglotCapabilityError formatted as "Could not invoke '{methodName}': {scrubbedMessage}". It signals that an argument supplied to the remote capability did not match the expected parameter type.

Solutions

1. Check the capability's registered signature and pass arguments matching the declared parameter types
2. Verify handles being passed are of the correct type/registration
3. Update the client SDK/version to match the host's capability contract
4. Scrub and read the {scrubbedMessage} detail to identify which parameter failed

Example fix

// before
await dispatcher.InvokeAsync("addResource", 42); // string expected
// after
await dispatcher.InvokeAsync("addResource", "my-resource");

// Validate argument types against the capability signature before invoking
if (arg is not string s) throw new ArgumentException("addResource expects a string", nameof(arg));

bool IsMatchingType(object? arg, Type expected) => arg is null ? !expected.IsValueType || Nullable.GetUnderlyingType(expected) is not null : expected.IsInstanceOfType(arg);

try { await dispatcher.InvokeAsync(methodName, args); }
catch (PolyglotCapabilityError ex) when (ex.Code == "TYPE_MISMATCH") { /* fix argument types per capability signature */ }

When it happens

Trigger: InvokeAsync -> a capability registration's target method throws ArgumentException detected by IsTypeMismatchException (e.g. wrong enum/parameter value type), commonly when a client passes an argument of the wrong shape via the polyglot/ATS bridge.

Common situations: Cross-language (polyglot) clients passing JS/Python values that don't map to the CLR parameter type; handle misuse (passing a handle of the wrong kind); stale clients calling capabilities after signature changes.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Command line args must be strings
• Could not invoke ' ' because parameter ' ' expects , but…
• Handle ' ' contains , expected
• Invalid type for option
• Model must be a FoundryModel or a string model name.

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/c4e7304330b72ac0. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.RemoteHost/Ats/CapabilityDispatcher.cs:566

        try
        {
            return await registration.Handler(args, _handles).ConfigureAwait(false);
        }
        catch (PolyglotCapabilityInvocationException ex)
        {
            activity.SetError(ex);
            throw ex.ToCapabilityException();
        }
        catch (CapabilityException ex)
        {
            activity.SetError(ex);
            throw;
        }
        catch (ArgumentException ex) when (IsTypeMismatchException(ex))
        {
            activity.SetError(ex);
            throw PolyglotCapabilityErrorFormatter.CreateInternalError(
                capabilityId,
                registration.Capability?.MethodName,
                registration.ClrMemberName,
                args,
                _handles,
                ex,
                _polyglotMethodNamesByClrName,
                registration.Capability?.TargetParameterName,
                errorCode: AtsErrorCodes.TypeMismatch).ToCapabilityException();
        }
        catch (ArgumentException ex)
        {
            activity.SetError(ex);
            throw CapabilityException.InvalidArgument(
                capabilityId,
                ex.ParamName ?? registration.Capability?.TargetParameterName ?? "unknown",
                ex.Message);
        }

View on GitHub (pinned to 25830f84bd)