{"record":{"id":"bab3d0c19669ef7f","repo":"jstedfast/MailKit","slug":"only-the-value-priv-and-value-shared-attributes-can-be-used","errorCode":null,"errorMessage":"Only the \"value.priv\" and \"value.shared\" attributes can be used for sorting.","messagePattern":"Only the \"value\\.priv\" and \"value\\.shared\" attributes can be used for sorting\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/Search/OrderByAnnotation.cs","lineNumber":66,"sourceCode":"\t\t/// <param name=\"order\">The sort order.</param>\n\t\t/// <exception cref=\"System.ArgumentNullException\">\n\t\t/// <para><paramref name=\"entry\"/> is <see langword=\"null\" />.</para>\n\t\t/// <para>-or-</para>\n\t\t/// <para><paramref name=\"attribute\"/>is <see langword=\"null\" />.</para>\n\t\t/// </exception>\n\t\t/// <exception cref=\"System.ArgumentException\">\n\t\t/// <paramref name=\"attribute\"/> is not a valid attribute for sorting.\n\t\t/// </exception>\n\t\tpublic OrderByAnnotation (AnnotationEntry entry, AnnotationAttribute attribute, SortOrder order) : base (OrderByType.Annotation, order)\n\t\t{\n\t\t\tif (entry is null)\n\t\t\t\tthrow new ArgumentNullException (nameof (entry));\n\n\t\t\tif (attribute is null)\n\t\t\t\tthrow new ArgumentNullException (nameof (attribute));\n\n\t\t\tif (attribute.Name != \"value\" || attribute.Scope == AnnotationScope.Both)\n\t\t\t\tthrow new ArgumentException (\"Only the \\\"value.priv\\\" and \\\"value.shared\\\" attributes can be used for sorting.\", nameof (attribute));\n\n\t\t\tEntry = entry;\n\t\t\tAttribute = attribute;\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Get the annotation entry.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// Gets the annotation entry.\n\t\t/// </remarks>\n\t\t/// <value>The annotation entry.</value>\n\t\tpublic AnnotationEntry Entry {\n\t\t\tget; private set;\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Get the annotation attribute.","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Search/OrderByAnnotation.cs#L48-L84","documentation":"IMAP ANNOTATE sorting only supports the \"value.priv\" and \"value.shared\" attributes on a single scope; sorting on any other attribute name, or an attribute with AnnotationScope.Both, is invalid and throws ArgumentException.","triggerScenarios":"Calling new OrderByAnnotation(entry, new AnnotationAttribute(\"value\"), order), any attribute named other than \"value.priv\"/\"value.shared\", or an attribute whose Scope is AnnotationScope.Both.","commonSituations":"Constructing an AnnotationAttribute(\"value\") without the .priv/.shared suffix; an attribute object deserialized or reused from another ANNOTATE context where Scope.Both was used.","solutions":["Use exactly \"value.priv\" or \"value.shared\" as the attribute name with a matching single scope.","Replace Scope.Both with a specific AnnotationScope.Private or AnnotationScope.Shared attribute.","Map arbitrary annotation attributes to one of the two sortable attributes before sorting."],"exampleFix":"// before\nvar attr = new AnnotationAttribute(\"value\");\nvar sort = new OrderByAnnotation(entry, attr, SortOrder.Ascending);\n// after\nvar attr = new AnnotationAttribute(\"value.priv\", AnnotationScope.Private);\nvar sort = new OrderByAnnotation(entry, attr, SortOrder.Ascending);","handlingStrategy":"validation","validationCode":"if (attribute.Name != \"value.priv\" && attribute.Name != \"value.shared\")\n    throw new ArgumentException(\"Only value.priv/value.shared can be used for sorting.\");\nif (attribute.Scope == AnnotationScope.Both)\n    throw new ArgumentException(\"Annotation scope must be Private or Shared for sorting.\");","typeGuard":"bool IsSortableAnnotation(AnnotationAttribute a) =>\n    a != null && (a.Name == \"value.priv\" || a.Name == \"value.shared\") && a.Scope != AnnotationScope.Both;","tryCatchPattern":"try\n{\n    var sort = new OrderByAnnotation(entry, attribute, order);\n}\ncatch (ArgumentException)\n{\n    sort = new OrderByAnnotation(entry, new AnnotationAttribute(\"value.priv\", AnnotationScope.Private), order);\n}","preventionTips":["Always include the .priv or .shared suffix in the attribute name.","Never use AnnotationScope.Both attributes for SORT; pick one scope.","Validate annotation attributes against the IMAP ANNOTATE-Extension sortable set before constructing sorts."],"tags":["mailkit","sorting","annotation","imap"],"backgroundTag":"invalid-argument-value","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}