jstedfast/MailKit · error · FormatException

An annotation entry must begin with a '/' character.

Error message

An annotation entry must begin with a '/' character.

What it means

AnnotationEntry.Parse throws FormatException when the first character of the entry is not '/', '*', or '%'. IMAP annotation entries are rooted at '/' (or use '*'/'%' mailbox-wildcard forms per RFC 5257); any other prefix is syntactically invalid.

Solutions

1. Prepend '/' to the entry name before parsing: "/" + entry
2. Keep the full entry string exactly as the server returned it (do not strip the leading character)
3. If you only have an entry name plus scope, use the AnnotationEntry constructor instead of Parse

Example fix

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

if (!string.IsNullOrEmpty (entry) && entry[0] != '/' && entry[0] != '*' && entry[0] != '%')
    entry = "/" + entry;

bool IsEntryShaped (string? entry) =>
    !string.IsNullOrEmpty (entry) && (entry[0] == '/' || entry[0] == '*' || entry[0] == '%');

try {
    var annotation = AnnotationEntry.Parse (entry);
} catch (FormatException ex) {
    logger.LogError (ex, "Malformed annotation entry: {Entry}", entry);
}

When it happens

Trigger: Calling Parse with strings like "comment", "vendor.cmu", or "/comment" minus the slash (e.g. "comment.priv") — i.e. entry[0] not in {'/','*','%'}.

Common situations: Stripping the leading '/' from a server-returned entry before re-parsing it; storing entries without the leading slash in config; confusing entry names with full 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.

Related errors

• Invalid annotation entry.
• 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/d7bc6167ead293b3. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:433

		/// </remarks>
		/// <param name="entry">The annotation entry.</param>
		/// <returns>The parsed annotation entry.</returns>
		/// <exception cref="System.ArgumentNullException">
		/// <paramref name="entry"/> is <see langword="null" />.
		/// </exception>
		/// <exception cref="System.FormatException">
		/// <paramref name="entry"/> does not conform to the annotation entry syntax.
		/// </exception>
		public static AnnotationEntry Parse (string entry)
		{
			if (entry == null)
				throw new ArgumentNullException (nameof (entry));

			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;

View on GitHub (pinned to 9d3859a785)