jstedfast/MailKit · error · ArgumentException

Invalid character in annotation entry path

Error message

Invalid character in annotation entry path: '{c}'.

What it means

AnnotationEntry.ValidatePath throws ArgumentException when any character after the first is > 127 (non-ASCII). IMAP annotation entry paths are restricted to ASCII (astring characters), so characters like accents, emoji, or CJK text are rejected with a message naming the offending character.

Solutions

1. Replace all non-ASCII characters in the path with ASCII equivalents before constructing AnnotationEntry.
2. Validate the path in UI/input code to restrict it to ASCII characters (code point <= 127).
3. If a localized label is needed, store it in the annotation value, not the entry path.

Example fix

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

static bool IsAscii(string s) => s != null && s.All(c => c <= 127);
if (!IsAscii(path))
    throw new FormatException("Annotation entry path must be ASCII only");

bool IsAsciiEntryPath(string p) => p != null && p.Length > 0 && p.All(c => c <= 127);

try
{
    var entry = new AnnotationEntry(path, AnnotationScope.Shared);
}
catch (ArgumentException ex) when (ex.Message.Contains("Invalid character"))
{
    // transliterate or reject non-ASCII input
}

When it happens

Trigger: Calling `new AnnotationEntry("/commentaire-café", scope)` or paths built from localized/user-provided text containing any character with code point above 127.

Common situations: Localizing annotation keys; user-supplied annotation names; copy-pasting paths containing typographic quotes, non-breaking spaces, or accented letters.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

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

Related errors

• Annotation entry paths must begin with '/'.
• Annotation entry paths must not include a part-specifier.
• Invalid 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/16aec3024f035b80. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:135

			if (path.Length == 0)
				throw new ArgumentException ("Annotation entry paths cannot be empty.", nameof (path));

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

View on GitHub (pinned to 9d3859a785)