{"record":{"id":"aed762b2147708a4","repo":"jstedfast/MailKit","slug":"you-must-enable-utf-8-mode-before-authenticating","errorCode":null,"errorMessage":"You must enable UTF-8 mode before authenticating.","messagePattern":"You must enable UTF-8 mode before authenticating\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Pop3/Pop3Client.cs","lineNumber":1591,"sourceCode":"\n\t\t\tengine.Disconnected -= OnEngineDisconnected;\n\t\t\tdisconnecting = utf8 = false;\n\t\t\toctets = total = 0;\n\t\t\tengine.Uri = null;\n\n\t\t\tif (host != null)\n\t\t\t\tOnDisconnected (host, port, options, requested);\n\t\t}\n\n\t\t#endregion\n\n\t\tbool CheckCanEnableUTF8 ()\n\t\t{\n\t\t\tCheckDisposed ();\n\t\t\tCheckConnected ();\n\n\t\t\tif (engine.State != Pop3EngineState.Connected)\n\t\t\t\tthrow new InvalidOperationException (\"You must enable UTF-8 mode before authenticating.\");\n\n\t\t\tif ((engine.Capabilities & Pop3Capabilities.UTF8) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The POP3 server does not support the UTF8 extension.\");\n\n\t\t\treturn !utf8;\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Enable UTF8 mode.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// The POP3 UTF8 extension allows the client to retrieve messages in the UTF-8 encoding and\n\t\t/// may also allow the user to authenticate using a UTF-8 encoded username or password.\n\t\t/// </remarks>\n\t\t/// <param name=\"cancellationToken\">The cancellation token.</param>\n\t\t/// <exception cref=\"System.ObjectDisposedException\">\n\t\t/// The <see cref=\"Pop3Client\"/> has been disposed.\n\t\t/// </exception>","sourceCodeStart":1573,"sourceCodeEnd":1609,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Pop3/Pop3Client.cs#L1573-L1609","documentation":"Pop3Client.EnableUTF8 (or an API that depends on it) throws this InvalidOperationException when the engine state is no longer plain 'Connected' - meaning the session has already moved past the pre-auth stage (authentication has begun or completed). UTF-8 mode must be enabled via the UTF8 command after connecting but before authenticating. MailKit enforces this protocol ordering strictly.","triggerScenarios":"Calling EnableUTF8 after Authenticate has run; calling EnableUTF8 twice in a row (second call sees non-Connected state); calling it inside a re-authentication flow after the session is already authenticated.","commonSituations":"Automated pipelines that authenticate first and then try to switch to UTF-8 for mailbox access; retry logic that re-invokes EnableUTF8 after a partially completed login; misunderstanding that UTF8 can be toggled anytime.","solutions":["Call EnableUTF8 immediately after Connect and before any Authenticate call.","Reorder your login sequence: Connect -> EnableUTF8 -> Authenticate.","If already authenticated, disconnect and reconnect, then enable UTF-8 before authenticating.","Remove duplicate EnableUTF8 calls in retry/loop code."],"exampleFix":"// before\nclient.Connect (host, port);\nclient.Authenticate (user, pass);\nclient.EnableUTF8 ();\n// after\nclient.Connect (host, port);\nclient.EnableUTF8 ();\nclient.Authenticate (user, pass);","handlingStrategy":"validation","validationCode":"// EnableUTF8 must run while state is Connected (pre-auth)\nif (!client.IsConnected || client.IsAuthenticated)\n    throw new InvalidOperationException (\"Call EnableUTF8 after Connect and before Authenticate\");","typeGuard":null,"tryCatchPattern":"try {\n    client.EnableUTF8 (cancellationToken);\n} catch (InvalidOperationException) {\n    // session already past Connected state: reconnect and redo in correct order\n}","preventionTips":["Fix the sequence: Connect -> EnableUTF8 -> Authenticate","Guard EnableUTF8 calls with a flag so retries/loops don't invoke it twice","Never call EnableUTF8 after Authenticate in any code path"],"tags":["pop3","utf8","state-machine","mailkit","ordering"],"backgroundTag":"invalid-state-transition","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"}