What causes "Error parsing URIs from configuration value '{key}'." in microsoft/aspire?

Set the config value (env var/appsettings) to a valid absolute URI including the scheme, e.g. 'https://host:port'

microsoft/aspire · error · InvalidOperationException

Error parsing URIs from configuration value

Error message

Error parsing URIs from configuration value '{key}'.

What it means

IConfigurationExtensions.GetUri reads a configuration value and parses it as an absolute Uri; any failure (null value, relative URI, malformed string, or unexpected exception during parsing) is rethrown as an InvalidOperationException with the config key in the message and the original exception as InnerException.

Solutions

Set the config value (env var/appsettings) to a valid absolute URI including the scheme, e.g. 'https://host:port'
Check the exact key name matches between configuration source and GetUri call
Inspect InnerException to see whether the value was null or malformed
If the value is optional, use the Try/nullable variant or check configuration key existence before calling
Trim the value of stray whitespace/quotes in the configuration source

Example fix

// before
// ASPIRE_ENDPOINT=http://myhost:18888  (was: myhost:18888)
var endpoint = configuration.GetUri("ASPIRE_ENDPOINT");
// after — with corrected config value the call succeeds
var endpoint = configuration.GetUri("ASPIRE_ENDPOINT"); // https://myhost:18888
// or defensively:
var raw = configuration["ASPIRE_ENDPOINT"];
var endpoint = Uri.TryCreate(raw, UriKind.Absolute, out var uri) ? uri : new Uri("https://localhost:18888");

Defensive patterns

Strategy: validation

Validate before calling

var raw = configuration[key];
if (!Uri.TryCreate(raw, UriKind.Absolute, out _))
    throw new InvalidOperationException($"Config '{key}' must be an absolute URI, got: '{raw}'.");

Type guard

static bool IsValidAbsoluteUri(string? s) => Uri.TryCreate(s, UriKind.Absolute, out var u) && (u.Scheme == Uri.UriSchemeHttp || u.Scheme == Uri.UriSchemeHttps);

Try / catch

try { return configuration.GetUri(key); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Invalid URI in config '{Key}' (inner: {Inner})", key, ex.InnerException?.Message); throw; }

Prevention

Always store URLs with explicit http(s):// scheme in config
Trim whitespace when writing config values
Validate required URI config keys at startup with fail-fast checks

When it happens

Trigger: Calling GetUri(configuration, key) where the key is missing, has an empty value, or contains a string that is not an absolute, well-formed URI (e.g. 'localhost:8080' without scheme, 'http:/broken', relative paths).

Common situations: Missing environment variable or appsettings entry for an endpoint URL; URL stored without the 'http(s)://' scheme; typo in the config key; value containing whitespace or quotes copied from a document.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

Thrown at src/Shared/IConfigurationExtensions.cs:135

    [return: NotNullIfNotNull(nameof(defaultValue))]
    public static Uri? GetUri(this IConfiguration configuration, string key, Uri? defaultValue = null)
    {
        try
        {
            var uri = configuration[key];

            if (string.IsNullOrWhiteSpace(uri))
            {
                return defaultValue;
            }
            else
            {
                return new Uri(uri, UriKind.Absolute);
            }
        }
        catch (Exception ex)
        {
            throw new InvalidOperationException($"Error parsing URIs from configuration value '{key}'.", ex);
        }
    }

    /// <summary>
    /// Parses a configuration value's semicolon-delimited value into an array of <see cref="Uri"/> objects.
    /// </summary>
    /// <param name="configuration">The <see cref="IConfiguration"/> this method extends.</param>
    /// <param name="key">The configuration key.</param>
    /// <param name="defaultValue">A default value, for when the configuration value is unspecified or white space. May be <see langword="null"/>.</param>
    /// <returns>The parsed values, or the default value if specified and parsing failed. Returns <see langword="null"/> if <paramref name="defaultValue"/> is <see langword="null"/> and parsing failed.</returns>
    /// <exception cref="InvalidOperationException">The configuration value could not be accessed, or contained incorrectly formatted data.</exception>
    [return: NotNullIfNotNull(nameof(defaultValue))]
    public static Uri[]? GetUris(this IConfiguration configuration, string key, Uri? defaultValue = null)
    {
        try
        {
            var uris = configuration[key];

View on GitHub (pinned to 25830f84bd)