jstedfast/MailKit · error · NotSupportedException

The IMAP server does not support the IDLE extension.

Error message

The IMAP server does not support the IDLE extension.

What it means

Thrown as NotSupportedException when IdleAsync is called but the server's CAPABILITIES do not include the IDLE extension (RFC 2177). The client refuses to start an IDLE session the server cannot honor.

Solutions

1. Check (client.Capabilities & ImapCapabilities.Idle) != 0 before idling and fall back to NOOP polling
2. Use client.Supports(ImapCapabilities.Idle) as a guard
3. Switch to a server that supports RFC 2177 IDLE
4. Re-query capabilities after authentication if they were cached too early

Example fix

// before
await client.IdleAsync(folder, doneToken);
// after
if ((folder.Capabilities & ImapCapabilities.Idle) != 0)
    await client.IdleAsync(folder, doneToken);
else
    await PollWithNoopAsync(folder, doneToken);

bool canIdle = (client.Capabilities & ImapCapabilities.Idle) != 0;

try { await folder.IdleAsync(doneToken); }
catch (NotSupportedException) { StartNoopPolling(folder, doneToken); }

When it happens

Trigger: Calling IdleAsync or idle-based push notification code against a server without IDLE capability; stale capabilities cache taken before login when the capability only appears after AUTHENTICATE.

Common situations: Legacy or minimal IMAP servers (some proxies, Exchange front-ends) lacking IDLE; connecting to a gateway that strips extensions; using idle fallback logic that assumes universal IDLE support.

Related errors

• The IMAP server does not support the QRESYNC extension.
• The IMAP server does not support the UTF8=ACCEPT extension.
• The IMAP server does not support the ID extension.
• The doneToken must be cancellable.
• An ImapFolder has not been opened.

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapClient.cs:1922

		{
			var ic = QueueNoOpCommand (cancellationToken);

			engine.Run (ic);

			ProcessNoOpResponse (ic);
		}

		void CheckCanIdle (CancellationToken doneToken)
		{
			if (!doneToken.CanBeCanceled)
				throw new ArgumentException ("The doneToken must be cancellable.", nameof (doneToken));

			CheckDisposed ();
			CheckConnected ();
			CheckAuthenticated ();

			if ((engine.Capabilities & ImapCapabilities.Idle) == 0)
				throw new NotSupportedException ("The IMAP server does not support the IDLE extension.");

			if (engine.State != ImapEngineState.Selected)
				throw new InvalidOperationException ("An ImapFolder has not been opened.");
		}

		ImapCommand QueueIdleCommand (ImapIdleContext context, CancellationToken cancellationToken)
		{
			var ic = engine.QueueCommand (cancellationToken, null, "IDLE\r\n");
			ic.ContinuationHandler = context.ContinuationHandler;
			ic.UserData = context;

			return ic;
		}

		static void ProcessIdleResponse (ImapCommand ic)
		{
			ic.ThrowIfNotOk ("IDLE");
		}

View on GitHub (pinned to 9d3859a785)