microsoft/aspire · critical · InvalidOperationException

Could not determine an appropriate location for local…

Error message

Could not determine an appropriate location for local storage. Set the AspireStorePathKeyName setting to a folder where the App Host content should be stored.

What it means

AspireStore requires a local folder to persist AppHost content (state, caches, artifacts). It resolves the root from configuration key AspireStore.AspireStorePathKeyName; when that setting is missing or blank, the builder cannot determine where to store data and throws InvalidOperationException during service provider construction.

Solutions

Set the AspireStore path configuration key (AspireStore.AspireStorePathKeyName) to a writable folder, e.g. via environment variable or builder.Configuration.
Ensure HOME/USERPROFILE is set so default path resolution can succeed.
If running in a container/CI, mount or point the store at a persistent writable directory like /tmp or a workspace volume.

Example fix

// before: no store path configured
var builder = DistributedApplication.CreateBuilder(args);
// after
var builder = DistributedApplication.CreateBuilder(args);
builder.Configuration["AspireStore:Path"] = "/workdir/.aspire";

Defensive patterns

Strategy: validation

Validate before calling

var storePath = builder.Configuration[AspireStore.AspireStorePathKeyName];
if (string.IsNullOrWhiteSpace(storePath) || !Directory.Exists(storePath))
    builder.Configuration[AspireStore.AspireStorePathKeyName] = Path.GetTempPath();

Try / catch

try { var app = builder.Build(); } catch (InvalidOperationException ex) when (ex.Message.Contains("local storage")) { /* set the store path config key and retry */ }

Prevention

Set the Aspire store path explicitly in CI/containers where HOME may be unset.
Verify the configured path exists and is writable before building the app.
Mount a persistent volume for the store in containerized environments.

When it happens

Trigger: The configuration entry for the Aspire store path (e.g. env var ASPIRE_STORE_PATH style key) is unset or whitespace when DistributedApplicationBuilder's services are built, typically in non-standard hosting environments or stripped-down test hosts.

Common situations: Running the AppHost in CI containers or minimal images where the default user-profile/.aspire location can't be derived; custom hosts that don't propagate the store path configuration; HOME not set on Linux so the default path resolution fails.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/DistributedApplicationBuilder.cs:442

        _innerBuilder.Services.AddSingleton<LocaleOverrideContext>();
        _innerBuilder.Services.AddHealthChecks();
        _innerBuilder.Services.AddHttpClient();
        // Add the manifest publishing step to the pipeline
        Pipeline.AddManifestPublishing();
        _innerBuilder.Services.Configure<ResourceNotificationServiceOptions>(o =>
        {
            // Default to stopping on dependency failure if the dashboard is disabled. As there's no way to see or easily recover
            // from a failure in that case.
            o.DefaultWaitBehavior = options.DisableDashboard ? WaitBehavior.StopOnResourceUnavailable : WaitBehavior.WaitOnResourceUnavailable;
        });
        _innerBuilder.Services.AddSingleton<IAspireStore, AspireStore>(sp =>
        {
            var configuration = sp.GetRequiredService<IConfiguration>();
            var aspireDir = configuration[AspireStore.AspireStorePathKeyName];

            if (string.IsNullOrWhiteSpace(aspireDir))
            {
                throw new InvalidOperationException($"Could not determine an appropriate location for local storage. Set the {AspireStore.AspireStorePathKeyName} setting to a folder where the App Host content should be stored.");
            }

            var directoryService = sp.GetRequiredService<IFileSystemService>();
            return new AspireStore(Path.Combine(aspireDir, ".aspire"), directoryService);
        });
#pragma warning disable ASPIRECERTIFICATES001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
        _innerBuilder.Services.AddSingleton<IDeveloperCertificateService, DeveloperCertificateService>();
#pragma warning restore ASPIRECERTIFICATES001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

        // Shared DCP things (even though DCP isn't used in 'publish' and 'inspect' mode
        // we still honour the DCP options around container runtime selection.
        _innerBuilder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IConfigureOptions<DcpOptions>, ConfigureDefaultDcpOptions>());
        _innerBuilder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions<DcpOptions>, ValidateDcpOptions>());

        // Aspire CLI support
        _innerBuilder.Services.AddHostedService<CliOrphanDetector>();
        _innerBuilder.Services.AddSingleton<BackchannelService>();
        _innerBuilder.Services.AddHostedService<BackchannelService>(sp => sp.GetRequiredService<BackchannelService>());

View on GitHub (pinned to 25830f84bd)