{"record":{"id":"a2962eefb47de696","repo":"microsoft/aspire","slug":"unknown-type-category-typeref-category","errorCode":null,"errorMessage":"Unknown type category: {typeRef.Category}","messagePattern":"Unknown type category: (.+?)","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.RemoteHost/Ats/AtsMarshaller.cs","lineNumber":164,"sourceCode":"            return SerializeCancellationToken(cancellationToken);\n        }\n\n        // Handle 'any' type - fall back to runtime type inspection\n        if (typeRef.TypeId == TypeSystem.AtsConstants.Any)\n        {\n            return MarshalToJson(value);\n        }\n\n        return typeRef.Category switch\n        {\n            AtsTypeCategory.Handle => _handles.Marshal(value, typeRef.TypeId),\n            AtsTypeCategory.Primitive => SerializePrimitive(value),\n            AtsTypeCategory.Enum => JsonValue.Create(value.ToString()),\n            AtsTypeCategory.Dto => SerializeDto(value),\n            AtsTypeCategory.Array => SerializeArray(value, typeRef.ElementType),\n            AtsTypeCategory.List => _handles.Marshal(value, typeRef.TypeId),\n            AtsTypeCategory.Dict => _handles.Marshal(value, typeRef.TypeId),\n            _ => throw new InvalidOperationException($\"Unknown type category: {typeRef.Category}\")\n        };\n    }\n\n    /// <summary>\n    /// Marshals a .NET object to JSON for sending to the guest using a declared CLR type.\n    /// </summary>\n    /// <param name=\"value\">The value to marshal.</param>\n    /// <param name=\"declaredType\">The declared type that should be exposed to the guest.</param>\n    /// <returns>The JSON representation, or null if the value is null.</returns>\n    public JsonNode? MarshalToJson(object? value, Type declaredType)\n    {\n        if (value == null)\n        {\n            return null;\n        }\n\n        if (declaredType == typeof(object))\n        {","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.RemoteHost/Ats/AtsMarshaller.cs#L146-L182","documentation":"AtsMarshaller.MarshalToJson serializes a .NET value to JSON for the guest based on the AtsTypeRef's category. Each known category (Primitive, Enum, Dto, Array, List, Dict) has a dedicated branch; this throw is the exhaustive-match fallback, meaning the category value was not one of the recognized enum members. It signals an internal invariant violation: a new AtsTypeCategory member was added without updating the marshaller, or an uninitialized/corrupt category reached the switch.","triggerScenarios":"Calling MarshalToJson with a typeRef whose Category is not one of AtsTypeCategory.Primitive/Enum/Dto/Array/List/Dict (e.g. a newer category enum value marshalled by an older remote host assembly, or a default(AtsTypeRef) with an undefined category). Reached via SerializeArray -> MarshalToJson when recursing into array element types.","commonSituations":"Version skew where a guest sends a type reference using a newer AtsTypeCategory than the host's marshaller supports; a newly added AtsTypeCategory enum member whose branch was not implemented; corrupted or default-initialized AtsTypeRef values crossing the remote boundary.","solutions":["Update/redeploy the host assembly so its marshaller knows the category used by the type reference (matching version).","Check that the AtsTypeRef being marshalled was correctly registered/initialized (not a default value).","Pin host and guest to the same Ats package version so categories match.","If you control the code, add a case for the missing category in the switch expression."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (!Enum.IsDefined(typeof(AtsTypeCategory), typeRef.Category))\n    throw new InvalidOperationException($\"Category {typeRef.Category} is not marshalled by this host version.\");","typeGuard":"static bool IsKnownCategory(AtsTypeRef t) =>\n    t.Category is AtsTypeCategory.Primitive or AtsTypeCategory.Enum or AtsTypeCategory.Dto\n        or AtsTypeCategory.Array or AtsTypeCategory.List or AtsTypeCategory.Dict;","tryCatchPattern":null,"preventionTips":["Keep the AtsTypeCategory switch exhaustive so the compiler flags unhandled enum members.","Keep host and guest type-reference contracts on the same package version.","Avoid marshalling default(AtsTypeRef) / uninitialized category values."],"tags":["ats","serialization","type-system"],"backgroundTag":"internal-invariant-violation","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"}