git-ecosystem/git-credential-manager · error · ArgumentException

State key cannot be null or whitespace.

Error message

State key cannot be null or whitespace.

What it means

GitStateValidation.ValidateKey validates state entry keys used by the Git credential-helper 'state' wire protocol. A key that is null, empty, or whitespace-only cannot be serialized as a protocol line, so the library throws ArgumentException immediately.

Solutions

1. Ensure the key is a non-empty, non-whitespace string before calling SetState/WithState.
2. Validate inputs where the key is produced (config lookup, user input) and fail early with a clearer error.
3. If state is optional, skip SetState entirely when no key is available rather than passing null.

Example fix

// before
response.SetState(configValue, "1");
// after
if (!string.IsNullOrWhiteSpace(configValue))
{
    response.SetState(configValue, "1");
}

if (string.IsNullOrWhiteSpace(key)) throw new ArgumentException("State key required");

static bool IsValidStateKey(string k) => !string.IsNullOrWhiteSpace(k);

try { response.SetState(key, value); }
catch (ArgumentException e) when (e.Message.Contains("State key")) { /* log and skip state */ }

When it happens

Trigger: Calling GitResponse.SetState(key, value) or WithState(key, value) with a null, empty ("") or whitespace-only key, which funnels into ValidateKey.

Common situations: Building state keys dynamically (e.g. from config values or dictionary keys) where the source can be missing or blank; typos passing "" as a literal.

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

• State key cannot contain '=', newline, or NUL characters.
• State key cannot start with
• State value cannot contain newline or NUL characters.
• State value cannot be null.
• Must specify at least one AuthenticationModes

AI-assisted analysis of git-ecosystem/git-credential-manager@e8ce762cd0 (2026-09-11). Data as JSON: /api/errors/975ecb09a5f01a32. Report an issue: GitHub.

Appendix: source

Thrown at src/Core/GitStateValidation.cs:83

        {
            if (c == LF || c == NUL)
            {
                return false;
            }
        }

        return true;
    }

    /// <summary>
    /// Throws <see cref="ArgumentException"/> if <paramref name="key"/> is not
    /// a legal state entry key.
    /// </summary>
    public static void ValidateKey(string key)
    {
        if (string.IsNullOrWhiteSpace(key))
        {
            throw new ArgumentException("State key cannot be null or whitespace.", nameof(key));
        }

        foreach (char c in key)
        {
            if (c == EQ || c == LF || c == NUL)
            {
                throw new ArgumentException(
                    "State key cannot contain '=', newline, or NUL characters.",
                    nameof(key));
            }
        }

        if (key.StartsWith(Constants.CredentialProtocol.GcmStatePrefix, StringComparison.Ordinal))
        {
            throw new ArgumentException(
                $"State key cannot start with '{Constants.CredentialProtocol.GcmStatePrefix}'; " +
                "the prefix is reserved and added automatically when state is emitted.",
                nameof(key));

View on GitHub (pinned to e8ce762cd0)