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

SmtpClient.Capabilities setter is designed only to disable server-advertised capabilities (by masking them off). If the assigned value contains any bit not already in `capabilities`, the expression (capabilities | value) > capabilities is true and it throws ArgumentException, because enabling a capability the server did not advertise would lie about the protocol state.

Solutions

Only assign masked-off values: client.Capabilities &= ~SmtpCapabilities.FeatureToDisable.
To require a capability, check client.Capabilities.HasFlag(...) after connecting instead of setting it.
Do not assign SmtpCapabilities.All or bits the server did not advertise.

Example fix

// before
client.Capabilities = SmtpCapabilities.Pipelining; // throws
// after
client.Capabilities &= ~SmtpCapabilities.UTF8; // disable UTF8
bool canPipeline = client.Capabilities.HasFlag(SmtpCapabilities.Pipelining); // check instead

Defensive patterns

Strategy: try-catch

Validate before calling

// only assign values that are a subset of current capabilities
if ((capabilities | value) > capabilities)
    throw new ArgumentException("Capabilities cannot be enabled, they may only be disabled.");

Type guard

bool IsDisableOnly(SmtpCapabilities current, SmtpCapabilities value) => (current | value) == current;

Try / catch

try {
    client.Capabilities &= ~SmtpCapabilities.UTF8;
} catch (ArgumentException ex) {
    // attempted to enable a capability the server never advertised
    logger.LogWarning(ex, "Attempted to enable a non-advertised capability");
}

Prevention

Use &= ~SmtpCapabilities.X to disable; never assign new bits
Use HasFlag to query capabilities instead of writing them
Never assign SmtpCapabilities.All to the setter

When it happens

Trigger: Setting client.Capabilities = SmtpCapabilities.SomeFeature (or SmtpCapabilities.All) where SomeFeature is not already part of the negotiated capability set.

Common situations: Developers trying to force-enable extensions like PIPELINING or UTF8 on a server that did not advertise them; copying capability flags from another client instance.

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

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

Appendix: source

Thrown at MailKit/Net/Smtp/SmtpClient.cs:263

		/// <summary>
		/// Get the capabilities supported by the SMTP 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\SmtpExamples.cs" region="Capabilities"/>
		/// </example>
		/// <value>The capabilities.</value>
		/// <exception cref="System.ArgumentException">
		/// Capabilities cannot be enabled, they may only be disabled.
		/// </exception>
		public SmtpCapabilities Capabilities {
			get { return capabilities; }
			set {
				if ((capabilities | value) > capabilities)
					throw new ArgumentException ("Capabilities cannot be enabled, they may only be disabled.", nameof (value));

				capabilities = value;
			}
		}

		/// <summary>
		/// Get or set the local domain.
		/// </summary>
		/// <remarks>
		/// The local domain is used in the HELO or EHLO commands sent to
		/// the SMTP server. If left unset, the local IP address will be
		/// used instead.
		/// </remarks>
		/// <value>The local domain.</value>
		public string? LocalDomain {
			get; set;
		}

View on GitHub (pinned to 9d3859a785)