jstedfast/MailKit · error · ArgumentNullException

Value cannot be null. (Parameter 'metadata')

Error message

Value cannot be null. (Parameter 'metadata')

What it means

QueueSetMetadataCommand throws ArgumentNullException when its MetadataCollection argument is null. Setting metadata requires a collection instance; to clear entries you set null values inside the collection rather than passing a null collection.

Solutions

1. Pass a new MetadataCollection() (empty collections simply queue nothing)
2. To erase a metadata entry, add the tag with a null value instead of passing a null collection
3. Validate the collection non-null before calling

Example fix

// before
MetadataCollection metadata = null;
folder.SetMetadata(metadata, ct);
// after
var metadata = new MetadataCollection { { MetadataTag.Comment, null } }; // clears /comment
folder.SetMetadata(metadata, ct);

if (metadata == null)
    throw new ArgumentException("Metadata collection is required", nameof(metadata));

bool IsValidMetadata(MetadataCollection m) => m != null;

try {
    folder.SetMetadata(metadata, ct);
} catch (ArgumentNullException ex) {
    logger.LogError(ex, "Null metadata collection passed to SetMetadata");
    throw;
}

When it happens

Trigger: Calling ImapFolder.SetMetadata(MetadataCollection, CancellationToken) with a null collection, often from an unassigned variable or a null deserialized payload.

Common situations: Intending to 'delete all metadata' by passing null instead of a collection with null-valued entries; building metadata conditionally and leaving the variable null.

Related errors

• Value cannot be null. (Parameter 'options')
• Value cannot be null. (Parameter 'tags')
• partSpecifier
• text
• Value cannot be null. (Parameter 'name')

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

Appendix: source

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

		/// <exception cref="ImapCommandException">
		/// The server replied with a NO or BAD response.
		/// </exception>
		public override async Task<MetadataCollection> GetMetadataAsync (MetadataOptions options, IEnumerable<MetadataTag> tags, CancellationToken cancellationToken = default)
		{
			var ic = QueueGetMetadataCommand (options, tags, cancellationToken);

			if (ic == null)
				return new MetadataCollection ();

			await Engine.RunAsync (ic).ConfigureAwait (false);

			return ProcessGetMetadataResponse (ic, options);
		}

		ImapCommand? QueueSetMetadataCommand (MetadataCollection metadata, CancellationToken cancellationToken)
		{
			if (metadata == null)
				throw new ArgumentNullException (nameof (metadata));

			CheckState (false, false);

			if ((Engine.Capabilities & ImapCapabilities.Metadata) == 0)
				throw new NotSupportedException ("The IMAP server does not support the METADATA extension.");

			if (metadata.Count == 0)
				return null;

			var command = new StringBuilder ("SETMETADATA %F (");
			var args = new List<object> {
				this
			};

			for (int i = 0; i < metadata.Count; i++) {
				if (i > 0)
					command.Append (' ');

View on GitHub (pinned to 9d3859a785)