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

State value cannot contain newline or NUL characters.

Error message

State value cannot contain newline or NUL characters.

What it means

State values are emitted as single 'key=value' protocol lines. A value containing LF or NUL would break the line framing (and '=' is allowed in values because only the first '=' splits), so ValidateValue throws ArgumentException for newline or NUL characters.

Solutions

1. Flatten the value: replace newlines with a safe delimiter like ' ' or '\\n' literal.
2. Encode the value (Base64 or URL-encoding) before storing and decode when reading back.
3. Split multi-line content into multiple state entries.

Example fix

// before
response.SetState("last-error", exception.ToString());
// after
response.SetState("last-error", exception.ToString().Replace('\n', ' ').Replace('\r', ' '));

bool ok = value != null && value.IndexOfAny(new[] {'\n', '\r', '\0'}) < 0;

static bool IsSingleLineValue(string v) => v is not null && !v.Any(c => c == '\n' || c == '\0');

try { response.SetState(key, value); }
catch (ArgumentException e) when (e.Message.Contains("cannot contain")) { response.SetState(key, Convert.ToBase64String(Encoding.UTF8.GetBytes(value))); }

When it happens

Trigger: Calling SetState/WithState with a value containing '\n', '\r\n', or '\0' — commonly multi-line payloads, JSON blobs, or error text.

Common situations: Storing multi-line messages, base64 with newlines inserted, or raw process output as state; serializing objects without escaping.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• State key cannot contain '=', newline, or NUL characters.
• State key cannot be null or whitespace.
• State key cannot start with
• 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/bbc1fd89707a41c7. Report an issue: GitHub.

Appendix: source

Thrown at src/Core/GitStateValidation.cs:120

        }
    }

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

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

View on GitHub (pinned to e8ce762cd0)