RicoSuter/NSwag · error · InvalidOperationException

Could not parse variables, ensure that they are in the form…

Error message

Could not parse variables, ensure that they are in the form 'key1=value1,key2=value2', variables: " + variables

What it means

NSwagDocumentBase.ConvertVariables parses the document's variable string of 'key1=value1,key2=value2' pairs into a dictionary. Any parse failure (missing '=', empty pair, comma/format problems) is wrapped in this InvalidOperationException that echoes the raw variables string.

Solutions

Format variables strictly as key=value pairs separated by commas, e.g. 'key1=value1,key2=value2'.
Ensure every pair contains exactly one '=' with non-empty key and value.
Escape or remove commas/'=' inside values, or pass variables via the document/parameter API that supports arrays.

Example fix

// before
nswag run nswag.json /variables:"a=1;b=2"
// after
nswag run nswag.json /variables:"a=1,b=2"

Defensive patterns

Strategy: validation

Validate before calling

bool IsValidVariables(string s) => string.IsNullOrEmpty(s) ||
    s.Split(',').Where(p => !string.IsNullOrEmpty(p)).All(p => p.Split('=').Length == 2 && p.Split('=')[0].Length > 0);

Try / catch

try { await document.LoadAsync(inputPath, variables, outputPath); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Could not parse variables"))
{ Console.Error.WriteLine($"Fix /variables format (key1=value1,key2=value2): {ex.Message}"); throw; }

Prevention

Use strict 'key=value' pairs separated by commas only.
Avoid '=' or ',' inside values, or escape/encode them.
Shell-quote the whole /variables value to prevent truncation.
Pre-validate the string with the checker above before calling LoadAsync.

When it happens

Trigger: LoadAsync receives a variables argument that does not strictly match key=value pairs separated by commas — e.g. 'a=1,b' (missing value), 'a==1', 'a' (no '='), or values containing unescaped '='/' , ' patterns where Split('=')[1] is out of range.

Common situations: Passing env-style lists with semicolons instead of commas; quoting values; passing '--variables' values from scripts where the value got truncated; a single value with multiple '=' signs (base64 values).

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

AI-assisted analysis of RicoSuter/NSwag@63daf8fcc3 (2026-09-14). Data as JSON: /api/errors/a1cc69e21036787f. Report an issue: GitHub.

Appendix: source

Thrown at src/NSwag.Commands/NSwagDocumentBase.cs:283

            {
                value = JsonConvert.ToString(value);
                return value.Substring(1, value.Length - 2);
            }

            return string.Empty;
        }

        private static Dictionary<string, string> ConvertVariables(string variables)
        {
            try
            {
                return (variables ?? "")
                    .Split(',').Where(p => !string.IsNullOrEmpty(p))
                    .ToDictionary(p => p.Split('=')[0], p => p.Split('=')[1]);
            }
            catch (Exception exception)
            {
                throw new InvalidOperationException("Could not parse variables, ensure that they are " +
                                                    "in the form 'key1=value1,key2=value2', variables: " + variables, exception);
            }
        }

        private static JsonSerializerSettings GetSerializerSettings()
        {
            return new JsonSerializerSettings
            {
                DefaultValueHandling = DefaultValueHandling.Include,
                NullValueHandling = NullValueHandling.Include,
                ContractResolver = new CamelCasePropertyNamesContractResolver(),
                Converters =
                [
                    new StringEnumConverter()
                ]
            };
        }

View on GitHub (pinned to 63daf8fcc3)