microsoft/aspire · error · InvalidOperationException

The connection string

Error message

The connection string '{connectionName}' does not exist or is missing the file system name.

What it means

Aspire's DataLakeFileSystemClient component throws this when settings.FileSystemName is null or empty. A file-system-scoped client must know which file system (container in ADLS terms) to target; the library validates this before constructing the client.

Solutions

Set "Aspire:Azure:Storage:Files:DataLake": { "FileSystemName": "myfs" } in appsettings
Pass in code: .AddAzureDataLakeFileSystemClient("datalake", s => s.FileSystemName = "myfs")
Ensure the file system resource exists in the AppHost: dataLake.AddFileSystem("myfs")

Example fix

// before
builder.AddAzureDataLakeFileSystemClient("datalake"); // FileSystemName missing
// after
builder.AddAzureDataLakeFileSystemClient("datalake", s => s.FileSystemName = "myfs");

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrEmpty(builder.Configuration["Aspire:Azure:Storage:Files:DataLake:FileSystemName"]))
    throw new InvalidOperationException("FileSystemName must be set before adding the file system client.");

Prevention

Set FileSystemName via config or configureSettings
Create the file system resource in the AppHost with the same name
Add startup validation for ADLS keys

When it happens

Trigger: Calling builder.AddAzureDataLakeFileSystemClient(...) where the config section lacks FileSystemName and no configureSettings callback supplied it.

Common situations: File system declared in the AppHost but name not propagated to the consuming project; appsettings missing the FileSystemName key; renamed resource not reflected in config.

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/ce1f4790914a66bb. Report an issue: GitHub.

Appendix: source

Thrown at src/Components/Aspire.Azure.Storage.Files.DataLake/AspireDataLakeExtensions.DataLakeFileSystemComponent.cs:31

namespace Microsoft.Extensions.Hosting;

public static partial class AspireDataLakeExtensions
{
    private sealed class DataLakeFileSystemComponent
        : AzureComponent<AzureDataLakeFileSystemSettings, DataLakeFileSystemClient, DataLakeClientOptions>
    {
        protected override IAzureClientBuilder<DataLakeFileSystemClient, DataLakeClientOptions> AddClient(
            AzureClientFactoryBuilder azureFactoryBuilder,
            AzureDataLakeFileSystemSettings settings,
            string connectionName,
            string configurationSectionName)
            => ((IAzureClientFactoryBuilderWithCredential)azureFactoryBuilder)
                .RegisterClientFactory<DataLakeFileSystemClient, DataLakeClientOptions>(
                    (options, cred) =>
                    {
                        if (string.IsNullOrEmpty(settings.FileSystemName))
                        {
                            throw new InvalidOperationException(
                                $"The connection string '{connectionName}' does not exist or is missing the file system name.");
                        }

                        var connectionString = settings.ConnectionString;
                        if (string.IsNullOrEmpty(connectionString) && settings.ServiceUri is null)
                        {
                            throw new InvalidOperationException(
                                $"A DataLakeServiceClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a 'ConnectionString' or 'ServiceUri' in the '{configurationSectionName}' configuration section.");
                        }

                        var dataLakeServiceClient = !string.IsNullOrEmpty(connectionString) ?
                            new DataLakeServiceClient(connectionString, options) :
                            cred is not null ? new DataLakeServiceClient(settings.ServiceUri, cred, options) :
                                new DataLakeServiceClient(settings.ServiceUri, options);

                        var fileSystemClient = dataLakeServiceClient.GetFileSystemClient(settings.FileSystemName);

                        return fileSystemClient;

View on GitHub (pinned to 25830f84bd)