jstedfast/MailKit · error · FormatException

Invalid annotation entry.

Error message

Invalid annotation entry.

What it means

During parsing, AnnotationEntry.Parse throws FormatException with "Invalid annotation entry." when the structure after the leading character is malformed — here, when a digit follows '/' but a numeric component was already parsed (component > 0), meaning two part-number components were not separated correctly.

Solutions

1. Use the exact entry string returned by the IMAP server (e.g. from Fetch/GetAnnotations output) rather than hand-constructed ones
2. Validate the entry against RFC 5257 syntax: '/' ['.part'] path ('.priv'|'.shared'|'.priv.shared')
3. Catch FormatException around Parse and log/skip the offending entry
4. Round-trip: construct entries with AnnotationEntry.Create instead of parsing ad-hoc strings

Example fix

// before
var annotation = AnnotationEntry.Parse ("/1/2comment.priv");
// after
var annotation = AnnotationEntry.Parse ("/1.comment.priv");

static bool LooksLikeEntry (string entry) =>
    System.Text.RegularExpressions.Regex.IsMatch (
        entry, @"^[/*%](\.?\d+)?[^.]+(\.priv|\.shared|\.priv\.shared)$");

try {
    var annotation = AnnotationEntry.Parse (entry);
} catch (FormatException ex) {
    logger.LogError (ex, "Malformed annotation entry: {Entry}", entry);
    // skip or fall back to constructing via AnnotationEntry.Create
}

When it happens

Trigger: Parsing entries with misplaced digits after '/', e.g. "/1/2comment.priv", duplicate numeric components, or otherwise structurally broken entry strings that pass the first-character check but fail the component scanner.

Common situations: Hand-writing entry strings instead of using the server's exact format; corrupted or truncated entry strings from logs/config; entries from non-conformant servers.

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

• An annotation entry must begin with a '/' character.
• Value cannot be null. (Parameter 'entry')
• An annotation entry cannot be empty.
• Value cannot be null. (Parameter 'entry')
• Annotation entry paths must not end with '/'.

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

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:447

			if (entry.Length == 0)
				throw new FormatException ("An annotation entry cannot be empty.");

			if (entry[0] != '/' && entry[0] != '*' && entry[0] != '%')
				throw new FormatException ("An annotation entry must begin with a '/' character.");

			var scope = AnnotationScope.Both;
			int startIndex = 0, endIndex;
			string? partSpecifier = null;
			var component = 0;
			var pc = entry[0];
			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}'.");

View on GitHub (pinned to 9d3859a785)