jstedfast/MailKit · error · FormatException
The format specifier is not supported.
Error message
The %{format[i]} format specifier is not supported. What it means
ImapCommand uses a printf-style format string (e.g. "LOGIN %S %S") to build IMAP commands; %S, %Q, etc. are the only supported specifiers. A FormatException is thrown when an unknown specifier appears, meaning MailKit itself passed a malformed internal format string or a subclass/user-built command used an invalid one.
Solutions
- Use only documented specifiers (%S, %Q and companions) in the command format string.
- Escape literal percent signs if the format mechanism supports it, or restructure so the '%' is part of an argument passed via %S.
- Check the MailKit source (ImapCommand.FormatCommand) for the exact supported specifier set in your version and upgrade if a needed specifier was added later.
Example fix
// before var ic = new ImapCommand(engine, token, null, "MYCMD %X", arg); // after var ic = new ImapCommand(engine, token, null, "MYCMD %S", arg.ToString());
Defensive patterns
Strategy: try-catch
Validate before calling
// pre-validate custom format strings before use bool IsValidSpecifier(char c) => "SLQ".Contains(c) || char.IsLetter(c) == false; // restrict to known set
Try / catch
try { ic = new ImapCommand(engine, token, null, format, args); } catch (FormatException ex) { throw new InvalidOperationException($"Bad command format '{format}': {ex.Message}", ex); } Prevention
- Use only specifiers documented in ImapCommand.FormatCommand for your MailKit version.
- Add a unit test that formats every command template your app builds.
- Avoid hand-building format strings from user input.
When it happens
Trigger: Passing a format string containing an unrecognized specifier (anything other than the supported set like %S, %Q) to command construction that formats arguments; a literal '%' in a command template not doubled/escaped properly.
Common situations: Custom IMAP extensions built on top of MailKit internals; MailKit version differences where a specifier was added later; typos in derived command builders.
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
- All folders must be ImapFolders.
- An annotation entry cannot be empty.
- An annotation entry must begin with a '/' character.
- An ImapFolder has not been opened.
- Annotation attribute specifiers cannot be empty.
AI-assisted analysis of jstedfast/MailKit@9d3859a785 (2026-09-15).
Data as JSON: /api/errors/0539905c2800d0dd.
Report an issue: GitHub.
Appendix: source
Thrown at MailKit/Net/Imap/ImapCommand.cs:232
builder.Append (LiteralTokenSuffix, 0, LiteralTokenSuffix.Length);
totalSize += length;
parts.Add (new ImapCommandPart (builder.ToArray (), literal, wait));
builder.Clear ();
if (prefix == UTF8LiteralTokenPrefix)
builder.Append ((byte) ')');
break;
case 'S': // a string which may need to be quoted or made into a literal
AppendString (options, true, builder, (string) args[argc++]);
break;
case 'Q': // similar to %S but string must be quoted at a minimum
AppendString (options, false, builder, (string) args[argc++]);
break;
default:
throw new FormatException ($"The %{format[i]} format specifier is not supported.");
}
} else if (format[i] < 128) {
builder.Append ((byte) format[i]);
} else {
int nchars = char.IsSurrogate (format[i]) ? 2 : 1;
int nbytes = Encoding.UTF8.GetBytes (format, i, nchars, utf8, 0);
builder.Append (utf8, 0, nbytes);
i += nchars - 1;
}
}
parts.Add (new ImapCommandPart (builder.ToArray (), null));
}
/// <summary>
/// Initializes a new instance of the <see cref="MailKit.Net.Imap.ImapCommand"/> class.
/// </summary>
/// <remarks>View on GitHub (pinned to 9d3859a785)