jstedfast/MailKit · error · ArgumentNullException

Value cannot be null. (Parameter 'options')

Error message

Value cannot be null. (Parameter 'options')

What it means

The multi-tag QueueGetMetadataCommand validates its MetadataOptions argument and throws ArgumentNullException when it is null. MetadataOptions controls MAXSIZE/DEPTH parameters and must be an object (use a new MetadataOptions() for defaults), never null.

Solutions

1. Pass a new MetadataOptions() instead of null for default behavior
2. Initialize options at the call site before invoking GetMetadata
3. Validate options non-null at your API boundary

Example fix

// before
var values = folder.GetMetadata(null, tags, cancellationToken);
// after
var values = folder.GetMetadata(new MetadataOptions(), tags, cancellationToken);

if (options == null)
    throw new ArgumentException("Options are required; use new MetadataOptions()", nameof(options));

bool IsValidMetadataArgs(MetadataOptions o, IEnumerable<MetadataTag> t) => o != null && t != null;

try {
    var values = folder.GetMetadata(options, tags, ct);
} catch (ArgumentNullException ex) {
    logger.LogError(ex, "Invalid GetMetadata arguments: {Param}", ex.ParamName);
    throw;
}

When it happens

Trigger: Calling ImapFolder.GetMetadata(MetadataOptions, IEnumerable<MetadataTag>, CancellationToken) with null options, e.g. when a nullable options variable was never assigned.

Common situations: Passing null intending 'no options' instead of a default MetadataOptions instance; deserialization producing null options.

Related errors

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

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

Appendix: source

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

		/// <exception cref="ImapProtocolException">
		/// The server's response contained unexpected tokens.
		/// </exception>
		/// <exception cref="ImapCommandException">
		/// The server replied with a NO or BAD response.
		/// </exception>
		public override async Task<string?> GetMetadataAsync (MetadataTag tag, CancellationToken cancellationToken = default)
		{
			var ic = QueueGetMetadataCommand (tag, cancellationToken);

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

			return ProcessGetMetadataResponse (ic, tag);
		}

		ImapCommand? QueueGetMetadataCommand (MetadataOptions options, IEnumerable<MetadataTag> tags, CancellationToken cancellationToken)
		{
			if (options == null)
				throw new ArgumentNullException (nameof (options));

			if (tags == null)
				throw new ArgumentNullException (nameof (tags));

			CheckState (false, false);

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

			var command = new StringBuilder ("GETMETADATA %F");
			var args = new List<object> ();
			bool hasOptions = false;

			if (options.MaxSize.HasValue || options.Depth != 0) {
				command.Append (" (");
				if (options.MaxSize.HasValue) {
					command.Append ("MAXSIZE ");
					command.Append (options.MaxSize.Value.ToString (CultureInfo.InvariantCulture));

View on GitHub (pinned to 9d3859a785)