jstedfast/MailKit · error · ArgumentException

Annotation entry paths must begin with '/'.

Error message

Annotation entry paths must begin with '/'.

What it means

AnnotationEntry.ValidatePath throws ArgumentException when the path does not begin with '/', '*', or '%'. RFC 5257 annotation entries are slash-rooted hierarchies (e.g. "/comment"), and only the special standalone wildcards '*' and '%' may omit the leading slash.

Solutions

1. Prefix the path with '/' if it is a rooted entry path missing the slash (e.g. "comment" -> "/comment").
2. Verify you are not passing an attribute specifier (like "value.privacy") where an entry path is expected.
3. Keep the standalone wildcards "*" or "%" if wildcard selection is intended.

Example fix

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

if (path != null && path.Length > 0 && path[0] != '/' && path != "*" && path != "%")
    path = "/" + path; // normalize to a rooted entry path
var entry = new AnnotationEntry(path, AnnotationScope.Shared);

bool IsValidEntryPath(string p) => !string.IsNullOrEmpty(p) && (p[0] == '/' || p == "*" || p == "%");

try
{
    var entry = new AnnotationEntry(path, AnnotationScope.Shared);
}
catch (ArgumentException ex) when (ex.ParamName == "path")
{
    // normalize: ensure leading '/' then retry or report
}

When it happens

Trigger: Calling `new AnnotationEntry("comment", ...)` or `new AnnotationEntry("/comment".TrimStart('/'), ...)` — any path whose first char is not '/' or a wildcard.

Common situations: Passing a bare attribute-like name without the leading slash; stripping the leading '/' accidentally via trimming or normalization code; confusing attribute specifiers (unrooted, e.g. "value.privacy") with entry paths (rooted).

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

• Annotation entry paths must not include a part-specifier.
• Invalid character in annotation entry path
• 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/4060a264d99c5ce9. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:121

		/// <summary>
		/// An annotation entry for a shared alternate subject on a message.
		/// </summary>
		/// <remarks>
		/// Used to get or set a shared alternate subject on a message.
		/// </remarks>
		public static readonly AnnotationEntry SharedAltSubject = new AnnotationEntry ("/altsubject", AnnotationScope.Shared);

		static void ValidatePath (string path)
		{
			if (path == null)
				throw new ArgumentNullException (nameof (path));

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

View on GitHub (pinned to 9d3859a785)