{"record":{"id":"732b314db7432888","repo":"jstedfast/MailKit","slug":"the-utf8-extension-has-not-been-enabled","errorCode":null,"errorMessage":"The UTF8 extension has not been enabled.","messagePattern":"The UTF8 extension has not been enabled\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolder.cs","lineNumber":4410,"sourceCode":"\n\t\t\t\tProcessExpungeResponse (ic);\n\t\t\t}\n\t\t}\n\n\t\tFormatOptions CreateAppendOptions (FormatOptions options)\n\t\t{\n\t\t\tif (options.International && (Engine.Capabilities & ImapCapabilities.UTF8Accept) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support the UTF8 extension.\");\n\n\t\t\tvar format = options.Clone ();\n\t\t\tformat.NewLineFormat = NewLineFormat.Dos;\n\t\t\tformat.EnsureNewLine = true;\n\n\t\t\tif ((Engine.Capabilities & ImapCapabilities.UTF8Only) == ImapCapabilities.UTF8Only)\n\t\t\t\tformat.International = true;\n\n\t\t\tif (format.International && !Engine.UTF8Enabled)\n\t\t\t\tthrow new InvalidOperationException (\"The UTF8 extension has not been enabled.\");\n\n\t\t\treturn format;\n\t\t}\n\n\t\tImapCommand QueueAppendCommand (FormatOptions options, IAppendRequest request, CancellationToken cancellationToken)\n\t\t{\n\t\t\tif (options == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (options));\n\n\t\t\tif (request == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (request));\n\n\t\t\tCheckState (false, false);\n\n\t\t\tvar format = CreateAppendOptions (options);\n\n\t\t\tif (request.Annotations != null && request.Annotations.Count > 0 && (Engine.Capabilities & ImapCapabilities.Annotate) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support annotations.\");","sourceCodeStart":4392,"sourceCodeEnd":4428,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolder.cs#L4392-L4428","documentation":"After capability checks pass, CreateAppendOptions verifies Engine.UTF8Enabled. A server may support UTF8 (capability present, so format.International stays true) but the client never issued ENABLE UTF8, so the extension is not active on the connection; Append then fails with InvalidOperationException.","triggerScenarios":"Calling Append/AppendAsync with an International FormatOptions (or server is UTF8=ONLY) when ImapClient.EnableUTF8() was never called for the current connection.","commonSituations":"Reconnecting after a dropped connection without re-issuing EnableUTF8 (capabilities/enabled state resets per session); upgrading a server to UTF8=ONLY while client code still assumes default behavior; forgetting EnableUTF8 after adding internationalization support.","solutions":["Call imapClient.EnableUTF8() after authentication and before Append when using International options.","Check client.UTF8Enabled before appending and enable or downgrade options accordingly.","If the server is UTF8Only, you must enable UTF8 — there is no non-UTF8 path.","Re-run EnableUTF8 on every new/reconnected session."],"exampleFix":"// before\nclient.Connect (...); client.Authenticate (...);\nfolder.Append (internationalOptions, request);\n// after\nclient.Connect (...); client.Authenticate (...);\nif ((client.Capabilities & ImapCapabilities.UTF8Accept) != 0)\n    client.EnableUTF8 ();\nfolder.Append (internationalOptions, request);","handlingStrategy":"validation","validationCode":"if (options.International && !client.UTF8Enabled && (client.Capabilities & ImapCapabilities.UTF8Accept) != 0) client.EnableUTF8 ();","typeGuard":"bool Utf8Ready (ImapClient c) => c.UTF8Enabled || (c.Capabilities & ImapCapabilities.UTF8Accept) == 0;","tryCatchPattern":"try { folder.Append (options, request); } catch (InvalidOperationException ex) when (ex.Message.Contains (\"UTF8\")) { client.EnableUTF8 (); folder.Append (options, request); }","preventionTips":["Issue EnableUTF8() right after authentication when using international options","Re-issue EnableUTF8 after every reconnect — state is per-session","Track server UTF8Only servers; they require UTF8 enabled for all operations"],"tags":["imap","mailkit","utf8","session-state","append"],"backgroundTag":"feature-not-enabled","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"}