jstedfast/MailKit · error · ArgumentException

Capabilities cannot be enabled, they may only be disabled.

Error message

Capabilities cannot be enabled, they may only be disabled.

What it means

ImapClient.Capabilities is settable only to REMOVE capabilities (a mask of features the client should pretend not to support). The setter throws ArgumentException if the value would enable any capability not already present, because MailKit never allows the client to invent capabilities the server did not offer.

Solutions

1. Only assign values that are a subset of the current Capabilities (use AND to intersect)
2. To disable a feature, use value &= ~ImapCapabilities.SomeBit or Capabilities & ~flag
3. To use an extension, the SERVER must support it — verify with client.Capabilities after connecting

Example fix

// before
client.Capabilities |= ImapCapabilities.Condstore; // would ENABLE - throws
// after
client.Capabilities &= ~ImapCapabilities.Condstore; // disable only

if ((client.Capabilities | value) > client.Capabilities)
	throw new InvalidOperationException("Capabilities mask may only remove features.");

bool IsCapabilitySubset(ImapCapabilities current, ImapCapabilities value)
	=> (current | value) == current;

try {
	client.Capabilities = mask;
} catch (ArgumentException) {
	client.Capabilities = client.Capabilities & mask; // intersect instead
}

When it happens

Trigger: Assigning `client.Capabilities = ImapCapabilities.QuickResync` (or OR-ing in new bits) when that bit is not already in engine.Capabilities, e.g. copying a capabilities enum from another client or using bitwise OR instead of AND-NOT.

Common situations: Trying to force-enable an extension the server didn't advertise; misunderstanding the property as a general set (it is a disable-mask); migrating code that set capabilities on a different library.

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.

Related errors

• Annotation entry paths must not end with '/'.
• Annotation entry paths must not end with '.'.
• Invalid part-specifier.
• The uid is invalid.
• offset

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapClient.cs:174

		/// <remarks>
		/// The capabilities will not be known until a successful connection has been made via one of
		/// the <a href="Overload_MailKit_Net_Imap_ImapClient_Connect.htm">Connect</a> methods and may
		/// change as a side-effect of calling one of the
		/// <a href="Overload_MailKit_Net_Imap_ImapClient_Authenticate.htm">Authenticate</a>
		/// methods.
		/// </remarks>
		/// <example>
		/// <code language="c#" source="Examples\ImapExamples.cs" region="Capabilities"/>
		/// </example>
		/// <value>The capabilities.</value>
		/// <exception cref="System.ArgumentException">
		/// Capabilities cannot be enabled, they may only be disabled.
		/// </exception>
		public ImapCapabilities Capabilities {
			get { return engine.Capabilities; }
			set {
				if ((engine.Capabilities | value) > engine.Capabilities)
					throw new ArgumentException ("Capabilities cannot be enabled, they may only be disabled.", nameof (value));

				engine.Capabilities = value;
			}
		}

		/// <summary>
		/// Get the maximum size of a message that can be appended to a folder.
		/// </summary>
		/// <remarks>
		/// <para>Gets the maximum size of a message, in bytes, that can be appended to a folder.</para>
		/// <note type="note">If the value is not set, then the limit is unspecified.</note>
		/// </remarks>
		/// <value>The append limit.</value>
		public uint? AppendLimit {
			get { return engine.AppendLimit; }
		}

		/// <summary>

View on GitHub (pinned to 9d3859a785)