jstedfast/MailKit · error · ArgumentException

The name is not a legal folder name.

Error message

The name is not a legal folder name.

What it means

MailKit throws this ArgumentException from QueueCreateCommand when the folder name supplied to CreateFolder fails ImapEngine.IsValidMailboxName. The name contains characters illegal on this server's hierarchy (e.g. the hierarchy separator, control characters, leading/trailing separator, or empty segments).

Solutions

1. Sanitize the name: strip or replace DirectorySeparator, control characters, and wildcard chars (% *) before calling CreateFolder.
2. Use ImapEngine.IsValidMailboxName(name, folder.DirectorySeparator) as a pre-check in your own code.
3. Use folder.ToString()/FullName of an existing folder as a template for valid naming conventions on this server.
4. Trim leading/trailing separators and collapse empty hierarchy segments in user-supplied names.

Example fix

// before
folder.CreateFolder(userInput + "/");

// after
var name = userInput.Trim('/').Replace("/", "-");
if (ImapEngine.IsValidMailboxName(name, folder.DirectorySeparator))
    folder.CreateFolder(name);

bool ok = name != null && ImapEngine.IsValidMailboxName(name, folder.DirectorySeparator);
if (!ok) throw new FormatException("invalid mailbox name");

try { folder.CreateFolder(name); } catch (ArgumentException ex) { logger.Warn(ex, "invalid folder name"); }

When it happens

Trigger: Calling folder.CreateFolder(name) (or client.GetFolder(...).CreateFolder) with a name containing the DirectorySeparator char in a bad position, invalid characters (non-UTF-8 encodable, control chars, '/' when separator differs), or a name the engine's validator rejects.

Common situations: Building folder names by concatenating user input with '/' on servers where the separator is '.'; names with trailing slashes from web UIs; names containing IMAP-special characters like '%', '*' which are wildcards; names with newlines from CSV imports.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• The uid is invalid.
• offset
• count
• The destination folder does not belong to this ImapClient.
• Cannot rename a folder using itself as the new parent…

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolder.cs:833

				folder.ParentFolder = this;
				folder.Id = id;

				if (specialUse)
					Engine.AssignSpecialFolder (folder);

				Engine.OnFolderCreated (folder);
			}

			return folder;
		}

		ImapCommand QueueCreateCommand (string name, bool isMessageFolder, CancellationToken cancellationToken, out string encodedName)
		{
			if (name == null)
				throw new ArgumentNullException (nameof (name));

			if (!ImapEngine.IsValidMailboxName (name, DirectorySeparator))
				throw new ArgumentException ("The name is not a legal folder name.", nameof (name));

			CheckState (false, false);

			if (!string.IsNullOrEmpty (FullName) && DirectorySeparator == '\0')
				throw new InvalidOperationException ("Cannot create child folders.");

			var fullName = !string.IsNullOrEmpty (FullName) ? FullName + DirectorySeparator + name : name;
			encodedName = Engine.EncodeMailboxName (fullName);
			var createName = encodedName;

			if (!isMessageFolder && Engine.QuirksMode != ImapQuirksMode.GMail)
				createName += DirectorySeparator;

			return Engine.QueueCommand (cancellationToken, null, "CREATE %S\r\n", createName);
		}

		MailboxIdResponseCode? ProcessCreateResponse (ImapCommand ic)
		{

View on GitHub (pinned to 9d3859a785)