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

Pop3Client.Capabilities setter only allows disabling capabilities that the engine currently reports: if the new value would add capability bits beyond the current engine capabilities, an ArgumentException is thrown. The property exists to force-disable features (like pipelining or top) for compatibility, never to enable ones the server didn't advertise.

Solutions

1. Only assign a subset: value &= existing client.Capabilities before setting, or set individual flags you want disabled.
2. If the server genuinely supports a feature MailKit didn't detect, fix capability detection (e.g. the server's CAPA response) rather than forcing the flag.
3. To disable, mask off the unwanted bit: client.Capabilities &= ~Pop3Capabilities.Pipelining;

Example fix

// before
client.Capabilities = Pop3Capabilities.Pipelining | Pop3Capabilities.Top;

// after
// only disable, never enable:
client.Capabilities &= ~Pop3Capabilities.Pipelining;

var requested = Pop3Capabilities.Pipelining;
if ((requested & ~client.Capabilities) != 0)
    throw new InvalidOperationException("can only disable capabilities the server advertised");

When it happens

Trigger: Assigning client.Capabilities = Pop3Capabilities pipelined values that include bits not already present, e.g. setting Pop3Capabilities.Pipelining when the server never advertised it, or OR-ing in extra flags.

Common situations: Trying to 'force-enable' a feature the server doesn't support to work around a capability detection problem; copying Capabilities flags from another client instance onto a fresh connection.

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

• The host name cannot be empty.
• One or more of the indexes are invalid.
• array
• uri
• visitor

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

Appendix: source

Thrown at MailKit/Net/Pop3/Pop3Client.cs:161

		/// <summary>
		/// Gets the capabilities supported by the POP3 server.
		/// </summary>
		/// <remarks>
		/// The capabilities will not be known until a successful connection has been made 
		/// and may change once the client is authenticated.
		/// </remarks>
		/// <example>
		/// <code language="c#" source="Examples\Pop3Examples.cs" region="Capabilities"/>
		/// </example>
		/// <value>The capabilities.</value>
		/// <exception cref="System.ArgumentException">
		/// Capabilities cannot be enabled, they may only be disabled.
		/// </exception>
		public Pop3Capabilities 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>
		/// Gets the expiration policy.
		/// </summary>
		/// <remarks>
		/// <para>If the server supports the EXPIRE capability (<see cref="Pop3Capabilities.Expire"/>), the value
		/// of the <see cref="ExpirePolicy"/> property will reflect the value advertized by the server.</para>
		/// <para>A value of <c>-1</c> indicates that messages will never expire.</para>
		/// <para>A value of <c>0</c> indicates that messages that have been retrieved during the current session
		/// will be purged immediately after the connection is closed via the <c>QUIT</c> command.</para>
		/// <para>Values larger than <c>0</c> indicate the minimum number of days that the server will retain
		/// messages which have been retrieved.</para>
		/// </remarks>
		/// <example>

View on GitHub (pinned to 9d3859a785)