jstedfast/MailKit · error · ArgumentException

Annotation entry paths must not include a part-specifier.

Error message

Annotation entry paths must not include a part-specifier.

What it means

AnnotationEntry.ValidatePath throws ArgumentException when the second character of the path is a digit, which in RFC 5257 denotes a MIME part specifier (e.g. "/1/comment"). Entry paths passed to AnnotationEntry must not embed a part specifier.

Solutions

1. Remove the part-specifier segment from the path (e.g. "/1/comment" -> "/comment").
2. Use the appropriate MailKit API overload that handles part-specific annotations rather than encoding the part number in the path.
3. If part annotation is required, verify the library version supports it and use the documented entry format.

Example fix

// before
var entry = new AnnotationEntry("/1/comment", AnnotationScope.Shared);
// after
var entry = new AnnotationEntry("/comment", AnnotationScope.Shared);

if (path != null && path.Length > 1 && path[1] >= '0' && path[1] <= '9')
    throw new FormatException("Entry path must not embed a MIME part specifier");
var entry = new AnnotationEntry(path, AnnotationScope.Shared);

bool HasPartSpecifier(string p) => p != null && p.Length > 1 && char.IsDigit(p[1]);

try
{
    var entry = new AnnotationEntry(path, AnnotationScope.Shared);
}
catch (ArgumentException ex) when (ex.ParamName == "path")
{
    // strip the part-specifier segment or use a part-aware API
}

When it happens

Trigger: Calling `new AnnotationEntry("/1/comment", scope)` or building paths like "/2.alt/text" that include a numeric part selector after the leading '/'.

Common situations: Constructing annotations for specific MIME parts of a message (bodypart annotations) by hand-embedding the part number instead of using the library's API that accepts part specifiers; copying paths from raw IMAP transcripts.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid annotation entry path.
• Annotation entry paths must begin with '/'.
• Invalid character in annotation entry path
• Value cannot be null. (Parameter 'specifier')
• Annotation attribute specifiers cannot be empty.

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

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:124

		/// </summary>
		/// <remarks>
		/// Used to get or set a shared alternate subject on a message.
		/// </remarks>
		public static readonly AnnotationEntry SharedAltSubject = new AnnotationEntry ("/altsubject", AnnotationScope.Shared);

		static void ValidatePath (string path)
		{
			if (path == null)
				throw new ArgumentNullException (nameof (path));

			if (path.Length == 0)
				throw new ArgumentException ("Annotation entry paths cannot be empty.", nameof (path));

			if (path[0] != '/' && path[0] != '*' && path[0] != '%')
				throw new ArgumentException ("Annotation entry paths must begin with '/'.", nameof (path));

			if (path.Length > 1 && path[1] >= '0' && path[1] <= '9')
				throw new ArgumentException ("Annotation entry paths must not include a part-specifier.", nameof (path));

			if (path == "*" || path == "%")
				return;

			char pc = path[0];

			for (int i = 1; i < path.Length; i++) {
				char c = path[i];

				if (c > 127)
					throw new ArgumentException ($"Invalid character in annotation entry path: '{c}'.", nameof (path));

				if (c >= '0' && c <= '9' && pc == '/')
					throw new ArgumentException ("Invalid annotation entry path.", nameof (path));

				if ((pc == '/' || pc == '.') && (c == '/' || c == '.'))
					throw new ArgumentException ("Invalid annotation entry path.", nameof (path));

View on GitHub (pinned to 9d3859a785)