jstedfast/MailKit · error · ArgumentException

Invalid part-specifier.

Error message

Invalid part-specifier.

What it means

AnnotationEntry.ValidatePartSpecifier rejects part specifiers that are not valid MIME part numbers. Each character must be a digit or '.', a '.' may not start the specifier or follow another '.', making strings like ".1", "1..2", or "text/html" invalid. Thrown as ArgumentException naming partSpecifier.

Solutions

1. Use only digit-and-dot MIME part numbers, e.g. "1", "1.2", "1.3.1"
2. Remove leading dots and collapse consecutive dots in the specifier
3. If annotating a non-numeric section, check whether a different overload or entry form is appropriate

Example fix

// before
var entry = AnnotationEntry.Create ("1..2", "comment", AnnotationScope.Shared);
// after
var entry = AnnotationEntry.Create ("1.2", "comment", AnnotationScope.Shared);

static bool IsValidPartSpecifier (string? s) =>
    !string.IsNullOrEmpty (s)
    && s.All (c => (c >= '0' && c <= '9') || c == '.')
    && !s.StartsWith (".") && !s.EndsWith (".") && !s.Contains ("..");

bool IsNumericPartSpecifier (string? s) =>
    s != null && System.Text.RegularExpressions.Regex.IsMatch (s, @"^\d+(\.\d+)*$");

try {
    var entry = AnnotationEntry.Create (partSpecifier, path, scope);
} catch (ArgumentException ex) when (ex.ParamName == "partSpecifier") {
    logger.LogError (ex, "Invalid part specifier: {Spec}", partSpecifier);
}

When it happens

Trigger: Passing a part specifier containing non-digit characters (e.g. "text", "1.A"), starting with '.', or containing consecutive dots ('.') to an AnnotationEntry constructor/factory.

Common situations: Confusing MIME section specifiers with body-part names like "text" or "HEADER" (valid elsewhere in IMAP but not here); building part paths with string joins that produce double dots.

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 end with '/'.
• Annotation entry paths must not end with '.'.
• Value cannot be null. (Parameter 'entry')
• Annotation entry paths must not include a part-specifier.
• Invalid annotation entry path.

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

Appendix: source

Thrown at MailKit/AnnotationEntry.cs:166

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

		static void ValidatePartSpecifier (string partSpecifier)
		{
			if (partSpecifier == null)
				throw new ArgumentNullException (nameof (partSpecifier));

			char pc = '\0';

			for (int i = 0; i < partSpecifier.Length; i++) {
				char c = partSpecifier[i];

				if (!((c >= '0' && c <= '9') || c == '.') || (c == '.' && (pc == '.' || pc == '\0')))
					throw new ArgumentException ("Invalid part-specifier.", nameof (partSpecifier));

				pc = c;
			}

			if (pc == '.')
				throw new ArgumentException ("Invalid part-specifier.", nameof (partSpecifier));
		}

		AnnotationEntry (string? partSpecifier, string entry, string path, AnnotationScope scope)
		{
			PartSpecifier = partSpecifier;
			Entry = entry;
			Path = path;
			Scope = scope;
		}

		/// <summary>
		/// Initializes a new instance of the <see cref="MailKit.AnnotationEntry"/> struct.

View on GitHub (pinned to 9d3859a785)