{"record":{"id":"b7427c05da8d7ebb","repo":"jstedfast/MailKit","slug":"the-imap-server-does-not-support-the-starttls-extension","errorCode":null,"errorMessage":"The IMAP server does not support the STARTTLS extension.","messagePattern":"The IMAP server does not support the STARTTLS extension\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/AsyncImapClient.cs","lineNumber":542,"sourceCode":"\n\t\t\tconnecting = true;\n\n\t\t\tvar imap = new ImapStream (stream, ProtocolLogger);\n\n\t\t\ttry {\n\t\t\t\tawait engine.ConnectAsync (imap, cancellationToken).ConfigureAwait (false);\n\t\t\t} catch {\n\t\t\t\tconnecting = false;\n\t\t\t\tthrow;\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\t// Only query the CAPABILITIES if the greeting didn't include them.\n\t\t\t\tif (engine.CapabilitiesVersion == 0)\n\t\t\t\t\tawait engine.QueryCapabilitiesAsync (cancellationToken).ConfigureAwait (false);\n\n\t\t\t\tif (options == SecureSocketOptions.StartTls && (engine.Capabilities & ImapCapabilities.StartTLS) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support the STARTTLS extension.\");\n\n\t\t\t\tif (starttls && (engine.Capabilities & ImapCapabilities.StartTLS) != 0) {\n\t\t\t\t\tvar ic = engine.QueueCommand (cancellationToken, null, \"STARTTLS\\r\\n\");\n\n\t\t\t\t\tawait engine.RunAsync (ic).ConfigureAwait (false);\n\n\t\t\t\t\tif (ic.Response == ImapCommandResponse.Ok) {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tvar tls = new ExtendedSslStream (stream, false, ValidateRemoteCertificate);\n\t\t\t\t\t\t\timap.SetStream (tls);\n\n\t\t\t\t\t\t\tawait SslHandshakeAsync (tls, host, cancellationToken).ConfigureAwait (false);\n\t\t\t\t\t\t} catch (Exception ex) {\n\t\t\t\t\t\t\tthrow SslHandshakeException.Create (ref sslValidationInfo, ex, true, \"IMAP\", host, port, 993, 143);\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tengine.IsSecure = true;\n","sourceCodeStart":524,"sourceCodeEnd":560,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/AsyncImapClient.cs#L524-L560","documentation":"When connecting with SecureSocketOptions.StartTls, MailKit checks the server's IMAP CAPABILITIES for the STARTTLS capability. If the server never advertised STARTTLS, upgrading the connection is impossible, so a NotSupportedException is thrown instead of sending credentials in plaintext.","triggerScenarios":"Connect(host, port, SecureSocketOptions.StartTls, ...) against a server whose CAPABILITIES response lacks STARTTLS — typically a server that only offers implicit TLS on port 993, or one with STARTTLS disabled in its config.","commonSituations":"Pointing the client at port 993 (implicit TLS) while requesting StartTls; server admins disabling STARTTLS; using a proxy/gateway that strips the capability; older or minimal IMAP servers without TLS support.","solutions":["Use SecureSocketOptions.SslOnConnect with port 993 if the server supports implicit TLS","If the server genuinely lacks TLS, use SecureSocketOptions.None (insecure; avoid) and confirm this is acceptable","Check server configuration to re-enable STARTTLS if it was disabled","Inspect the CAPABILITIES response (trace/log) to confirm what the server advertises"],"exampleFix":"// before\nawait client.ConnectAsync(\"imap.example.com\", 143, SecureSocketOptions.StartTls);\n// after\nawait client.ConnectAsync(\"imap.example.com\", 993, SecureSocketOptions.SslOnConnect);","handlingStrategy":"fallback","validationCode":"await client.ConnectAsync(host, port, SecureSocketOptions.None, cb); // then inspect\nbool supportsStartTls = (client.Capabilities & ImapCapabilities.StartTLS) != 0;","typeGuard":null,"tryCatchPattern":"try {\n\tawait client.ConnectAsync(host, port, SecureSocketOptions.StartTls);\n} catch (NotSupportedException) {\n\tawait client.ConnectAsync(host, 993, SecureSocketOptions.SslOnConnect); // implicit TLS fallback\n}","preventionTips":["Match SecureSocketOptions to the server's actual TLS model (993 implicit vs 143 STARTTLS)","Verify server CAPABILITIES once during deployment/health checks","Never fall back to plaintext without explicit approval"],"tags":["imap","tls","starttls","network","unsupported-feature"],"backgroundTag":"operation-not-supported","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}