microsoft/aspire · error · InvalidOperationException

The HTTP command prepare-request callback returned null.

Error message

The HTTP command prepare-request callback returned null.

What it means

The HTTP command's prepare-request callback is expected to return a populated export-data object describing the request (method, content, headers). If the callback returns null Aspire cannot build the HttpRequestMessage and throws InvalidOperationException.

Solutions

Ensure the prepare-request callback always returns a non-null HttpCommandRequestExportData instance
Add a default return (e.g. new HttpCommandRequestExportData { MethodName = "POST", Url = ... }) for all code paths
Validate the callback's inputs before returning and throw a descriptive exception if inputs are invalid instead of returning null

Example fix

// before
request => condition ? new HttpCommandRequestExportData { ... } : null
// after
request => new HttpCommandRequestExportData { MethodName = condition ? "PUT" : "POST", Url = url, ... }

Defensive patterns

Strategy: type-guard

Validate before calling

HttpCommandRequestExportData Prepare(...) {
  var data = BuildRequestData();
  return data ?? throw new InvalidOperationException("prepare-request produced null");
}

Type guard

bool PreparedNotNull(HttpCommandRequestExportData? d) => d is not null;

Try / catch

try { builder.WithHttpCommand(o => o.PrepareRequest = cb); }
catch (InvalidOperationException ex) when (ex.Message.Contains("prepare-request callback returned null")) { /* fix callback return paths */ }

Prevention

Ensure every code path of the prepare-request callback returns a value
Enable nullable reference types so a null return is flagged at compile time

When it happens

Trigger: Supplying an HttpCommandOptions.PrepareRequest callback (Func that maps a command context to HttpCommandRequestExportData) whose body returns null — e.g. an early-return path, or forgetting the return statement.

Common situations: Conditional prepare-request logic that skips returning data when a header/value is missing; refactoring that replaced the returned object with a local variable; copying a callback signature but not implementing the return.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ResourceBuilderExtensions.cs:3838

                {
                    ResourceName = context.ResourceName,
                    Endpoint = context.Endpoint,
                    CancellationToken = context.CancellationToken,
                    Arguments = context.Arguments
                }).ConfigureAwait(false);

                ApplyHttpCommandRequestExportData(context.Request, requestData);
            };
        }

        return commandOptions;
    }

    private static void ApplyHttpCommandRequestExportData(HttpRequestMessage request, HttpCommandRequestExportData requestData)
    {
        if (requestData is null)
        {
            throw new InvalidOperationException("The HTTP command prepare-request callback returned null.");
        }

        if (!string.IsNullOrWhiteSpace(requestData.MethodName))
        {
            request.Method = new HttpMethod(requestData.MethodName);
        }

        if (requestData.Content is not null)
        {
            request.Content = !string.IsNullOrWhiteSpace(requestData.ContentType)
                ? new StringContent(requestData.Content, Encoding.UTF8, requestData.ContentType)
                : new StringContent(requestData.Content, Encoding.UTF8);
        }
        else if (!string.IsNullOrWhiteSpace(requestData.ContentType))
        {
            throw new InvalidOperationException("HTTP command request content type cannot be specified without request content.");
        }

View on GitHub (pinned to 25830f84bd)