github/copilot-sdk · error · ArgumentException

The value cannot be an empty string or composed entirely of…

Error message

The value cannot be an empty string or composed entirely of whitespace.

What it means

This is thrown by a downlevel (polyfill) implementation of ArgumentNullException.ThrowIfNullOrWhiteSpace-style guards for runtimes lacking the modern APIs. It fires when an argument-guard helper (e.g. ValidateNotNullOrWhiteSpace) is given a string that is empty or whitespace-only, keeping argument validation consistent on older TFMs.

Solutions

Supply a non-empty, non-whitespace value for the argument before calling the API.
Guard with string.IsNullOrWhiteSpace and throw or substitute a valid default in your own code.
Fix the upstream source: check config files/env vars for empty values that get passed through.

Example fix

// before
session.SetName("");

// after
if (string.IsNullOrWhiteSpace(name)) throw new ArgumentException("Name required", nameof(name));
session.SetName(name);

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(value)) throw new ArgumentException("Value required and non-empty", nameof(value));

Type guard

static bool IsProvided(string? s) => !string.IsNullOrWhiteSpace(s);

Try / catch

try { api.Call(name); }
catch (ArgumentException ex) when (ex.Message.Contains("empty string or composed entirely of whitespace"))
{ logger.LogWarning("Argument {Param} was blank", ex.ParamName); }

Prevention

Validate string args with string.IsNullOrWhiteSpace at boundaries
Check env vars and config files for empty values before use
Never pass String.Empty as a placeholder for required names

When it happens

Trigger: Calling any library API whose parameter guard calls DownlevelArgumentExceptionExtensions with "", " ", "\t", or a whitespace-only string for a name/path/key-like argument (e.g. session name, tool name, event name).

Common situations: Reading a required value from environment variables or config files that exist but are empty; string.Split or trimming producing empty entries passed onward; users passing String.Empty as a placeholder for a required name.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/492c78af0ca87b28. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Polyfills/DownlevelExtensions.cs:55

                }
            }
        }
    }

    internal static class DownlevelArgumentExceptionExtensions
    {
        extension(ArgumentException)
        {
            public static void ThrowIfNullOrWhiteSpace(string? argument, [CallerArgumentExpression(nameof(argument))] string? paramName = null)
            {
                if (argument is null)
                {
                    throw new ArgumentNullException(paramName);
                }

                if (string.IsNullOrWhiteSpace(argument))
                {
                    throw new ArgumentException("The value cannot be an empty string or composed entirely of whitespace.", paramName);
                }
            }
        }
    }

    internal static class DownlevelDateTimeExtensions
    {
        extension(DateTime)
        {
            public static DateTime UnixEpoch => new(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
        }
    }

    internal static class DownlevelDateTimeOffsetExtensions
    {
        extension(DateTimeOffset)
        {
            public static DateTimeOffset UnixEpoch => new(1970, 1, 1, 0, 0, 0, TimeSpan.Zero);

View on GitHub (pinned to cd8cf15dc3)