jstedfast/MailKit · error · FormatException

Invalid character in part-specifier

Error message

Invalid character in part-specifier: '{c}'.

What it means

AnnotationEntry.Parse rejects part-specifier characters other than digits 0-9 and '.' separators. Any other character (letters, '-', spaces, etc.) inside the section digits makes the entry invalid per RFC 5257, so Parse throws FormatException.

Solutions

1. Ensure the part-specifier segment contains only digits and '.' separators (e.g. "1.2.3")
2. Move attribute names like 'text' or 'size' after the second '/', not into the part-specifier
3. Sanitize/validate the entry with a regex ^\d+(\.\d+)*$ before parsing

Example fix

// before
var entry = AnnotationEntry.Parse ("/1/text.priv"); // if intent was attribute
// after
var entry = AnnotationEntry.Parse ("/1/text.priv"); // correct; but "2.a/text.priv" -> "2/text.priv" or put attribute after 2nd slash

if (!System.Text.RegularExpressions.Regex.IsMatch (partSpecifier, @"^\d+(\.\d+)*$";))
    throw new ArgumentException ($"Invalid part-specifier: {partSpecifier}");

bool IsValidPartSpecifier (string spec) =>
    spec != null && spec.All (c => char.IsDigit (c) || c == '.');

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

When it happens

Trigger: Calling AnnotationEntry.Parse or Create with an entry containing a non-numeric, non-dot character in the part-specifier, e.g. "2.a/text.priv" or "1x/text.priv".

Common situations: Passing a MIME section name with letters (like 'text' or 'html') as the part-specifier, confusing the message-part path with the attribute path, typos in constructed entry strings.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Invalid part-specifier in annotation entry.
• 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/f3228b95b7d8ffa5. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:464

					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);
					i = startIndex = endIndex;
					component++;
				} else if (c == '/' || c == '.') {
					if (pc == '/' || pc == '.')
						throw new FormatException ("Invalid annotation entry path.");

View on GitHub (pinned to 9d3859a785)