microsoft/autogen · error · FormatException

Invalid key-value pair format: {kvString}; expecting "{keyNa

Error message

Invalid key-value pair format: {kvString}; expecting "{keyName}/{valueName}"

What it means

KVStringParseHelper.ToKVPair (a string extension) throws FormatException when the input does not match the expected "key/value" single-slash format captured by KVPairRegex. It is the standard parser for encoded AgentId/TopicId strings, so any malformed identifier string surfaces here.

Source

Thrown at dotnet/src/Microsoft.AutoGen/Contracts/KVStringParseHelper.cs:50

    /// </exception>
    /// <example>
    /// Example usage:
    /// <code>
    /// string input = "agent1/12345";
    /// var result = input.ToKVPair("Type", "Key");
    /// Console.WriteLine(result.Item1); // Outputs: agent1
    /// Console.WriteLine(result.Item2); // Outputs: 12345
    /// </code>
    /// </example>
    public static (string, string) ToKVPair(this string kvString, string keyName, string valueName)
    {
        var match = KVPairRegex.Match(kvString);
        if (match.Success)
        {
            return (match.Groups["key"].Value, match.Groups["value"].Value);
        }

        throw new FormatException($"Invalid key-value pair format: {kvString}; expecting \"{{{keyName}}}/{{{valueName}}}\"");
    }
}

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Fix the producer so the string is exactly type/key with both parts matching the AgentId rules.
2. If input may be URL-encoded, decode before parsing.
3. Validate with the same key/value pattern (printable ASCII, no extra slashes) before calling ToKVPair.

Example fix

// before
var (type, key) = "weather_agent%2Fdefault".ToKVPair("type", "key"); // throws: no literal '/'

// after
var (type, key) = Uri.UnescapeDataString("weather_agent%2Fdefault").ToKVPair("type", "key");

static readonly Regex KVPairRx = new("^[^/]+/[^/]+$");
bool IsParsableKV(string? s) => s is not null && KVPairRx.IsMatch(s);

static bool IsParsableKV(string? s) => s is not null && Regex.IsMatch(s, "^[^/]+/[^/]+$");

try { var (k, v) = s.ToKVPair("key", "value"); }
catch (FormatException) { /* log and reject the identifier at the boundary */ }

When it happens

Trigger: Calling kvString.ToKVPair(keyName, valueName) on strings like "keyvalue" (no slash), "a/b/c" (extra segments, depending on regex), "/value", "key/", or leading/trailing whitespace variants that fail KVPairRegex.

Common situations: Parsing AgentId.ToString() output that was hand-edited or truncated; reading agent/topic identifiers from URLs, query strings, or logs where the separator got mangled (URL encoding turning '/' into %2F); joining type and key with a different separator ('.', ':') by mistake.

Related errors

• Invalid agent id: {agent_id}
• Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0
• Invalid AgentId key: '{key}'. Must only contain ASCII charac
• Invalid agent type: {type}. Allowed values MUST match the re
• AgentInstantiationContext.agent_id() must be called within a

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/09099edc599ef8e2. Report an issue: GitHub.