jstedfast/MailKit · error · FormatException

Invalid part-specifier in annotation entry.

Error message

Invalid part-specifier in annotation entry.

What it means

MailKit's AnnotationEntry.Parse validates IMAP ANNOTATE entry part-specifiers (the '3.1' section digits between slashes). A part-specifier may not start with a separator after a slash, i.e. a '.' immediately following '/' is malformed, so Parse throws FormatException. This guards against entry strings like '/3.1/text' that violate RFC 5257 syntax.

Solutions

1. Fix the entry string so the part-specifier contains only digits and single '.' separators, with no leading or trailing '.' after '/'
2. Use AnnotationEntry.Create with a numeric part specifier string like "1.2" instead of embedding separators
3. Validate the part-specifier with a regex like ^\d+(\.\d+)*$ before calling Parse

Example fix

// before
var entry = AnnotationEntry.Parse ("/.1/text.priv");
// after
var entry = AnnotationEntry.Parse ("/1.1/text.priv");

static bool IsValidPartSpecifier (string entry) =>
    entry != null && System.Text.RegularExpressions.Regex.IsMatch (entry, @"^/\d+(\.\d)*/[^"]+";) ;

bool IsValidEntry (string entry) =>
    !string.IsNullOrEmpty (entry) && entry.StartsWith ("/") && System.Text.RegularExpressions.Regex.IsMatch (entry, @"^(/[0-9]+(\.[0-9]+)*)+/"," );

try { var entry = AnnotationEntry.Parse (input); }
catch (FormatException ex) { log.Warn ($"Bad annotation entry '{input}': {ex.Message}"); }

When it happens

Trigger: Calling AnnotationEntry.Parse or AnnotationEntry.Create with an entry whose part-specifier begins with '.' right after a '/' (e.g. "/.1/text" or "2/.text").

Common situations: Hand-constructed annotation entry strings, string concatenation that produces empty part segments (e.g. joining a section prefix with a separator), copying entry names from server logs with typos.

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 character in part-specifier
• Incomplete part-specifier in annotation entry.
• Value cannot be null. (Parameter 'specifier')
• Annotation attribute specifiers cannot be empty.
• Annotation attribute specifiers cannot contain '*' or '%'.

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

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:458

			string path;

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

				if (c >= '0' && c <= '9' && pc == '/') {
					if (component > 0)
						throw new FormatException ("Invalid annotation entry.");

					startIndex = i;
					endIndex = i + 1;
					pc = c;

					while (endIndex < entry.Length) {
						c = entry[endIndex];

						if (c == '/') {
							if (pc == '.')
								throw new FormatException ("Invalid part-specifier in annotation entry.");

							break;
						}

						if (!(c >= '0' && c <= '9') && c != '.')
							throw new FormatException ($"Invalid character in part-specifier: '{c}'.");

						if (c == '.' && pc == '.')
							throw new FormatException ("Invalid part-specifier in annotation entry.");

						endIndex++;
						pc = c;
					}

					if (endIndex >= entry.Length)
						throw new FormatException ("Incomplete part-specifier in annotation entry.");

					partSpecifier = entry.Substring (startIndex, endIndex - startIndex);

View on GitHub (pinned to 9d3859a785)