microsoft/aspire · error · JsonException

Cannot convert string

Error message

Cannot convert string '{value}' to boolean for key '{key}'. Expected 'true' or 'false'.

What it means

ParseBooleanString is the converter's flexible-string helper: it accepts 'true' and 'false' case-insensitively and throws JsonException for any other string, including the key being parsed in the message. This is the strict core of the 'flexible' boolean support — only true/false strings flex.

Solutions

Edit the JSON value for the named key to be exactly 'true' or 'false' (any casing).
Trace where the value originates (env var, script, another tool) and make that source emit canonical booleans.
If broader acceptance is needed, extend ParseBooleanString with mappings (yes/1/on => true) before the throw.

Example fix

// before
"featureFlags": { "MyFeature": "yes" }
// after
"featureFlags": { "MyFeature": "true" }

Defensive patterns

Strategy: validation

Validate before calling

static string? NormalizeBooleanString(string? s) =>
    s is null ? null :
    string.Equals(s, "true", StringComparison.OrdinalIgnoreCase) ? "true" :
    string.Equals(s, "false", StringComparison.OrdinalIgnoreCase) ? "false" :
    throw new FormatException($"'{s}' is not a boolean; use 'true' or 'false'.");

Type guard

static bool IsBooleanString(string? s) =>
    s is not null &&
    (string.Equals(s, "true", StringComparison.OrdinalIgnoreCase) ||
     string.Equals(s, "false", StringComparison.OrdinalIgnoreCase));

Try / catch

try
{
    var config = JsonSerializer.Deserialize<MyConfig>(json, options);
}
catch (JsonException ex) when (ex.Message.Contains("Cannot convert string") && ex.Message.Contains("to boolean"))
{
    logger.LogError(ex, "Config boolean flags must be 'true'/'false' strings.");
}

Prevention

Write only 'true' or 'false' (any casing) as string booleans.
Canonicalize values from env vars/scripts before writing them into config.
Use unquoted true/false literals to avoid string parsing entirely.

When it happens

Trigger: A string token in a Dictionary<string,bool> config object whose value is anything but 'true'/'false' in any casing, e.g. "MyFeature": "yes", "1", "on", "enabled", or "".

Common situations: Hand-edited config using natural-language booleans; values sourced from env vars or legacy config with 1/0 or yes/no conventions; documentation mismatch across tools.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/5c1f2cb827f1ede3. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Cli/Configuration/FlexibleBooleanDictionaryConverter.cs:84

            writer.WriteBoolean(kvp.Key, kvp.Value);
        }

        writer.WriteEndObject();
    }

    private static bool ParseBooleanString(string? value, string key)
    {
        if (string.Equals(value, "true", StringComparison.OrdinalIgnoreCase))
        {
            return true;
        }

        if (string.Equals(value, "false", StringComparison.OrdinalIgnoreCase))
        {
            return false;
        }

        throw new JsonException($"Cannot convert string '{value}' to boolean for key '{key}'. Expected 'true' or 'false'.");
    }
}

View on GitHub (pinned to 25830f84bd)