jstedfast/MailKit · error · ArgumentException

Invalid annotation entry path.

Error message

Invalid annotation entry path.

What it means

AnnotationEntry.ValidatePath throws the generic "Invalid annotation entry path" when a digit follows a '/' — meaning the path embeds a part specifier segment like "/1/". Per RFC 5257, digits immediately after a separator start a MIME part specifier, which is not allowed in AnnotationEntry paths.

Solutions

1. Remove the numeric part-specifier segment so the path segment after each '/' starts with a non-digit (e.g. "/1/comment" -> "/comment").
2. Use the library's supported API for part-specific annotations if needed.
3. Validate path segments before construction: reject segments beginning with a digit.

Example fix

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

bool HasDigitAfterSlash(string p) {
    for (int i = 1; i < p.Length; i++)
        if (char.IsDigit(p[i]) && p[i-1] == '/') return true;
    return false;
}
if (HasDigitAfterSlash(path))
    throw new FormatException("Path must not start a segment with a digit (part specifier)");

bool IsValidEntryPath(string p) => p != null && p.Length > 0 && p[0] != '/' || p == "*" || p == "%";

try
{
    var entry = new AnnotationEntry(path, AnnotationScope.Shared);
}
catch (ArgumentException ex) when (ex.Message == "Invalid annotation entry path.")
{
    // strip/repair the part-specifier segment before retrying
}

When it happens

Trigger: Calling `new AnnotationEntry("/1/comment", ...)` or "/2/text", where the second path character (or any character following '/') is a digit.

Common situations: Encoding MIME part numbers into entry paths by hand; converting raw IMAP annotation strings without stripping part specifiers; following documentation for part-level annotations incorrectly.

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

• Annotation entry paths must not include a part-specifier.
• 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/24e01d8ab87fdc4b. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:138

			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));

				pc = c;
			}

			int endIndex = path.Length - 1;

			if (path[endIndex] == '/')
				throw new ArgumentException ("Annotation entry paths must not end with '/'.", nameof (path));

			if (path[endIndex] == '.')
				throw new ArgumentException ("Annotation entry paths must not end with '.'.", nameof (path));
		}

		static void ValidatePartSpecifier (string partSpecifier)
		{

View on GitHub (pinned to 9d3859a785)