{"record":{"id":"2d8ab725d3376cc8","repo":"jstedfast/MailKit","slug":"capabilities-cannot-be-enabled-they-may-only-be-disabled-2d8ab7","errorCode":null,"errorMessage":"Capabilities cannot be enabled, they may only be disabled.","messagePattern":"Capabilities cannot be enabled, they may only be disabled\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Smtp/SmtpClient.cs","lineNumber":263,"sourceCode":"\t\t/// <summary>\n\t\t/// Get the capabilities supported by the SMTP server.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// The capabilities will not be known until a successful connection has been made\n\t\t/// and may change once the client is authenticated.\n\t\t/// </remarks>\n\t\t/// <example>\n\t\t/// <code language=\"c#\" source=\"Examples\\SmtpExamples.cs\" region=\"Capabilities\"/>\n\t\t/// </example>\n\t\t/// <value>The capabilities.</value>\n\t\t/// <exception cref=\"System.ArgumentException\">\n\t\t/// Capabilities cannot be enabled, they may only be disabled.\n\t\t/// </exception>\n\t\tpublic SmtpCapabilities Capabilities {\n\t\t\tget { return capabilities; }\n\t\t\tset {\n\t\t\t\tif ((capabilities | value) > capabilities)\n\t\t\t\t\tthrow new ArgumentException (\"Capabilities cannot be enabled, they may only be disabled.\", nameof (value));\n\n\t\t\t\tcapabilities = value;\n\t\t\t}\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Get or set the local domain.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// The local domain is used in the HELO or EHLO commands sent to\n\t\t/// the SMTP server. If left unset, the local IP address will be\n\t\t/// used instead.\n\t\t/// </remarks>\n\t\t/// <value>The local domain.</value>\n\t\tpublic string? LocalDomain {\n\t\t\tget; set;\n\t\t}\n","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Smtp/SmtpClient.cs#L245-L281","documentation":"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.","triggerScenarios":"Setting client.Capabilities = SmtpCapabilities.SomeFeature (or SmtpCapabilities.All) where SomeFeature is not already part of the negotiated capability set.","commonSituations":"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.","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."],"exampleFix":"// before\nclient.Capabilities = SmtpCapabilities.Pipelining; // throws\n// after\nclient.Capabilities &= ~SmtpCapabilities.UTF8; // disable UTF8\nbool canPipeline = client.Capabilities.HasFlag(SmtpCapabilities.Pipelining); // check instead","handlingStrategy":"try-catch","validationCode":"// only assign values that are a subset of current capabilities\nif ((capabilities | value) > capabilities)\n    throw new ArgumentException(\"Capabilities cannot be enabled, they may only be disabled.\");","typeGuard":"bool IsDisableOnly(SmtpCapabilities current, SmtpCapabilities value) => (current | value) == current;","tryCatchPattern":"try {\n    client.Capabilities &= ~SmtpCapabilities.UTF8;\n} catch (ArgumentException ex) {\n    // attempted to enable a capability the server never advertised\n    logger.LogWarning(ex, \"Attempted to enable a non-advertised capability\");\n}","preventionTips":["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"],"tags":["smtp","capabilities","setter"],"backgroundTag":"invalid-argument-value","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}