microsoft/aspire · error · ArgumentException

The provided extension socket path needs two valid parts.

Error message

The provided extension socket path needs two valid parts.

What it means

ConnectAsync parses the extension endpoint as host:port by splitting on ':'. The endpoint must yield exactly two parts with a valid port (integer, 1-65535); otherwise it throws an ArgumentException with this message (ErrorStrings.InvalidSocketPath), since TCP endpoints require both a host and a port.

Solutions

Set ASPIRE_EXTENSION_ENDPOINT to a plain 'host:port' pair, e.g. 127.0.0.1:54321 — no scheme, no path.
Re-copy the endpoint exactly as reported by the Aspire VS Code extension.
If IPv6 is involved, format the endpoint as expected by the parser (avoid bracketed literals; use an IPv4/hostname:port if supported).

Example fix

// before
export ASPIRE_EXTENSION_ENDPOINT=https://127.0.0.1:54321

// after
export ASPIRE_EXTENSION_ENDPOINT=127.0.0.1:54321

Defensive patterns

Strategy: validation

Validate before calling

var endpoint = Environment.GetEnvironmentVariable("ASPIRE_EXTENSION_ENDPOINT");
if (endpoint is null ||
    endpoint.Split(':') is not [var host, var portStr] ||
    !int.TryParse(portStr, out var port) || port is <= 0 or > 65535)
{
    throw new ArgumentException($"ASPIRE_EXTENSION_ENDPOINT must be 'host:port', got '{endpoint}'.");
}

Type guard

bool isValidEndpoint = endpoint?.Split(':') is [_, var p] && int.TryParse(p, out var pt) && pt is > 0 and <= 65535;

Try / catch

try { await backchannel.ConnectAsync(endpoint, ct); }
catch (ArgumentException ex) when (ex.Message.Contains("two valid parts"))
{ /* re-read endpoint from the extension as host:port */ }

Prevention

Set ASPIRE_EXTENSION_ENDPOINT as plain 'host:port' — no scheme, no path, no brackets.
Copy the endpoint value directly from the extension's reported endpoint.
Validate the endpoint format at configuration-load time.

When it happens

Trigger: Calling ConnectAsync with ASPIRE_EXTENSION_ENDPOINT set to a value that is not 'host:port' — e.g., a bare hostname, a full URL (https://host:port), an IPv6 literal, or a port outside 1-65535.

Common situations: Users paste the extension's full URL (with scheme or path) into ASPIRE_EXTENSION_ENDPOINT instead of host:port, or the token/tokenless env var is corrupted or truncated.

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 microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/e3c658f53bae884c. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Cli/Backchannel/ExtensionBackchannel.cs:261

                return;
            }

            try
            {
                using var activity = _activitySource.StartActivity();

                if (_rpcTaskCompletionSource.Task.IsCompleted)
                {
                    throw new InvalidOperationException($"Already connected to {Name} backchannel.");
                }

                _logger.LogDebug("Connecting to {Name} backchannel at {SocketPath}", Name, endpoint);
                var socket = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp);
                var addressParts = endpoint.Split(':');
                if (addressParts.Length != 2 || !int.TryParse(addressParts[1], out var port) || port <= 0 ||
                    port > 65535)
                {
                    throw new ArgumentException(string.Format(CultureInfo.CurrentCulture, ErrorStrings.InvalidSocketPath, endpoint));
                }

                await socket.ConnectAsync(addressParts[0], port, cancellationToken);
                _logger.LogDebug("Connected to {Name} backchannel at {SocketPath}", Name, endpoint);

                var stream = new SslStream(new NetworkStream(socket, true),
                    leaveInnerStreamOpen: true,
                    userCertificateValidationCallback: (_, c, _, e) =>
                    {
                        // Server certificate is already considered valid.
                        if (e == SslPolicyErrors.None)
                        {
                            return true;
                        }

                        if (c == null)
                        {
                            return false;

View on GitHub (pinned to 25830f84bd)