jstedfast/MailKit · error · ArgumentException

Only the "value.priv" and "value.shared" attributes can be…

Error message

Only the "value.priv" and "value.shared" attributes can be used for sorting.

What it means

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.

Solutions

1. Use exactly "value.priv" or "value.shared" as the attribute name with a matching single scope.
2. Replace Scope.Both with a specific AnnotationScope.Private or AnnotationScope.Shared attribute.
3. Map arbitrary annotation attributes to one of the two sortable attributes before sorting.

Example fix

// before
var attr = new AnnotationAttribute("value");
var sort = new OrderByAnnotation(entry, attr, SortOrder.Ascending);
// after
var attr = new AnnotationAttribute("value.priv", AnnotationScope.Private);
var sort = new OrderByAnnotation(entry, attr, SortOrder.Ascending);

if (attribute.Name != "value.priv" && attribute.Name != "value.shared")
    throw new ArgumentException("Only value.priv/value.shared can be used for sorting.");
if (attribute.Scope == AnnotationScope.Both)
    throw new ArgumentException("Annotation scope must be Private or Shared for sorting.");

bool IsSortableAnnotation(AnnotationAttribute a) =>
    a != null && (a.Name == "value.priv" || a.Name == "value.shared") && a.Scope != AnnotationScope.Both;

try
{
    var sort = new OrderByAnnotation(entry, attribute, order);
}
catch (ArgumentException)
{
    sort = new OrderByAnnotation(entry, new AnnotationAttribute("value.priv", AnnotationScope.Private), order);
}

When it happens

Trigger: 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.

Common situations: Constructing an AnnotationAttribute("value") without the .priv/.shared suffix; an attribute object deserialized or reused from another ANNOTATE context where Scope.Both was used.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Value cannot be null. (Parameter 'entry')
• An annotation entry cannot be empty.
• An annotation entry must begin with a '/' character.
• An ImapFolder has not been opened.
• Annotation attribute specifiers cannot be empty.

AI-assisted analysis of jstedfast/MailKit@9d3859a785 (2026-09-15). Data as JSON: /api/errors/bab3d0c19669ef7f. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/Search/OrderByAnnotation.cs:66

		/// <param name="order">The sort order.</param>
		/// <exception cref="System.ArgumentNullException">
		/// <para><paramref name="entry"/> is <see langword="null" />.</para>
		/// <para>-or-</para>
		/// <para><paramref name="attribute"/>is <see langword="null" />.</para>
		/// </exception>
		/// <exception cref="System.ArgumentException">
		/// <paramref name="attribute"/> is not a valid attribute for sorting.
		/// </exception>
		public OrderByAnnotation (AnnotationEntry entry, AnnotationAttribute attribute, SortOrder order) : base (OrderByType.Annotation, order)
		{
			if (entry is null)
				throw new ArgumentNullException (nameof (entry));

			if (attribute is null)
				throw new ArgumentNullException (nameof (attribute));

			if (attribute.Name != "value" || attribute.Scope == AnnotationScope.Both)
				throw new ArgumentException ("Only the \"value.priv\" and \"value.shared\" attributes can be used for sorting.", nameof (attribute));

			Entry = entry;
			Attribute = attribute;
		}

		/// <summary>
		/// Get the annotation entry.
		/// </summary>
		/// <remarks>
		/// Gets the annotation entry.
		/// </remarks>
		/// <value>The annotation entry.</value>
		public AnnotationEntry Entry {
			get; private set;
		}

		/// <summary>
		/// Get the annotation attribute.

View on GitHub (pinned to 9d3859a785)