jstedfast/MailKit · error · InvalidOperationException

You must enable UTF-8 mode before authenticating.

Error message

You must enable UTF-8 mode before authenticating.

What it means

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.

Solutions

1. Call EnableUTF8 immediately after Connect and before any Authenticate call.
2. Reorder your login sequence: Connect -> EnableUTF8 -> Authenticate.
3. If already authenticated, disconnect and reconnect, then enable UTF-8 before authenticating.
4. Remove duplicate EnableUTF8 calls in retry/loop code.

Example fix

// before
client.Connect (host, port);
client.Authenticate (user, pass);
client.EnableUTF8 ();
// after
client.Connect (host, port);
client.EnableUTF8 ();
client.Authenticate (user, pass);

// EnableUTF8 must run while state is Connected (pre-auth)
if (!client.IsConnected || client.IsAuthenticated)
    throw new InvalidOperationException ("Call EnableUTF8 after Connect and before Authenticate");

try {
    client.EnableUTF8 (cancellationToken);
} catch (InvalidOperationException) {
    // session already past Connected state: reconnect and redo in correct order
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• The POP3 server does not support the UTF8 extension.
• UTF8=ACCEPT needs to be enabled immediately after…
• The IMAP server does not support the UTF8=ACCEPT extension.
• The IMAP server does not support the UTF8 extension.
• The UTF8 extension has not been enabled.

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

Appendix: source

Thrown at MailKit/Net/Pop3/Pop3Client.cs:1591

			engine.Disconnected -= OnEngineDisconnected;
			disconnecting = utf8 = false;
			octets = total = 0;
			engine.Uri = null;

			if (host != null)
				OnDisconnected (host, port, options, requested);
		}

		#endregion

		bool CheckCanEnableUTF8 ()
		{
			CheckDisposed ();
			CheckConnected ();

			if (engine.State != Pop3EngineState.Connected)
				throw new InvalidOperationException ("You must enable UTF-8 mode before authenticating.");

			if ((engine.Capabilities & Pop3Capabilities.UTF8) == 0)
				throw new NotSupportedException ("The POP3 server does not support the UTF8 extension.");

			return !utf8;
		}

		/// <summary>
		/// Enable UTF8 mode.
		/// </summary>
		/// <remarks>
		/// The POP3 UTF8 extension allows the client to retrieve messages in the UTF-8 encoding and
		/// may also allow the user to authenticate using a UTF-8 encoded username or password.
		/// </remarks>
		/// <param name="cancellationToken">The cancellation token.</param>
		/// <exception cref="System.ObjectDisposedException">
		/// The <see cref="Pop3Client"/> has been disposed.
		/// </exception>

View on GitHub (pinned to 9d3859a785)