{"record":{"id":"db1900be7b2e91c2","repo":"microsoft/aspire","slug":"could-not-invoke-methodname-targetcontext-because-parameter","errorCode":null,"errorMessage":"Could not invoke '{methodName}'{targetContext} because parameter '{parameterName}' expects {expectedDescription}, but got {actualDescription}.","messagePattern":"Could not invoke '(.+?)'(.+?) because parameter '(.+?)' expects (.+?), but got (.+?)\\.","errorType":"exception","errorClass":"PolyglotCapabilityInvocationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.RemoteHost/Ats/PolyglotCapabilityInvocationException.cs","lineNumber":192,"sourceCode":"            innerException);\n    }\n\n    public static object ResolveHandleArgument(\n        string capabilityId,\n        string? polyglotMethodName,\n        JsonObject? args,\n        HandleRegistry handles,\n        string parameterName,\n        Type expectedType,\n        object handleObject,\n        string? targetParameterName = null)\n    {\n        if (TryConvertHandle(handleObject, expectedType, out var converted))\n        {\n            return converted!;\n        }\n\n        throw CreateTypeMismatch(\n            capabilityId,\n            polyglotMethodName,\n            args,\n            handles,\n            parameterName,\n            expectedType,\n            handleObject,\n            targetParameterName);\n    }\n\n    private static bool TryConvertHandle(object handleObject, Type expectedType, out object? converted)\n    {\n        if (expectedType.IsInstanceOfType(handleObject))\n        {\n            converted = handleObject;\n            return true;\n        }\n","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.RemoteHost/Ats/PolyglotCapabilityInvocationException.cs#L174-L210","documentation":"This error is thrown by ResolveHandleArgument in the remote host's polyglot (ATS) capability layer when an argument that should be a registered handle cannot be converted to the .NET type the capability method expects. Handles are opaque references clients hold to host-side objects (e.g., builders, resources); the host validates the handle's underlying object against the expected parameter type and throws a typed JSON-RPC type-mismatch exception listing the expected and actual descriptions when conversion fails.","triggerScenarios":"Calling a remote capability method (via exportApi/polyglot invocation over JSON-RPC) and passing, as a handle-typed parameter: (1) an unregistered or stale handle object, (2) a handle whose underlying object is of a different type than the parameter expects (e.g., passing a resource builder where a resource is required and the builder's Resource property does not match), or (3) a plain JSON value instead of a handle.","commonSituations":"A client script caches a handle across sessions where the host restarted and the handle registry was reset; a caller passes a builder handle to a method expecting the built resource of an incompatible type; a language binding serializes the handle incorrectly so the raw object arrives without handle identity; passing the wrong handle variable after refactoring client code.","solutions":["Check which parameter the message names and confirm the handle you pass was obtained from a capability call that returns that exact type.","Re-acquire the handle by re-invoking the creation API instead of reusing a cached handle across host restarts or reconnections.","If you have a builder handle but the method wants a resource, call the appropriate build/as method first and pass the returned handle.","Verify your client binding serializes handle references as handles (not raw JSON values) when constructing the args object."],"exampleFix":"// before\nvar endpoint = await client.InvokeAsync(\"GetEndpoint\", new JsonObject { [\"resource\"] = builderHandle });\n// after\nvar resourceHandle = await client.InvokeAsync(\"GetResource\", new JsonObject { [\"builder\"] = builderHandle });\nvar endpoint = await client.InvokeAsync(\"GetEndpoint\", new JsonObject { [\"resource\"] = resourceHandle });","handlingStrategy":"validation","validationCode":"function isHandleFor(value, expectedHandleName) {\n  return value !== null && typeof value === 'object' && '$handle' in value && value.$handle?.type === expectedHandleName;\n}","typeGuard":"function isValidHandle(value) {\n  return value !== null && typeof value === 'object' && typeof (value as any).$handle?.id === 'string';\n}","tryCatchPattern":"try {\n  await client.InvokeAsync(method, args);\n} catch (err) {\n  if (err.code === -32602 && /expects .* but got/.test(err.message)) {\n    const param = err.data?.parameterName;\n    handles = await reacquireHandles(); // re-create stale handles\n  }\n  throw err;\n}","preventionTips":["Re-acquire handles from creation APIs after any host restart or reconnect instead of caching them.","Track the return type of each capability call so each handle is only passed to parameters of the matching type.","Ensure your client binding serializes handle references as handles rather than plain JSON values.","Log handle identity alongside usage so mismatches point to the wrong variable quickly."],"tags":["json-rpc","type-mismatch","handles","remote-host","polyglot"],"backgroundTag":"type-mismatch","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}