OrchardCMS/OrchardCore · critical · FileStoreException

'UseHierarchicalNamespace' is set to 'true' but the storage…

Error message

'UseHierarchicalNamespace' is set to 'true' but the storage account does not have Hierarchical Namespace enabled. Correct the configuration or use a Gen2 storage account.

What it means

BlobFileStore.EnsureCapabilitiesAsync detects whether the Azure Storage account has Hierarchical Namespace (HNS, i.e. Data Lake Gen2) enabled and compares it with the configured UseHierarchicalNamespace override. This error is thrown when the override claims HNS=true but the detected account is not Gen2, because subsequent DataLake API calls would fail at runtime. Fail-fast prevents misleading downstream errors.

Solutions

1. Either enable Hierarchical Namespace on the storage account (a Gen2 account — usually requires creating a new account, HNS cannot always be toggled on existing ones), or set UseHierarchicalNamespace=false / remove the override so it is auto-detected.
2. Verify the account with: az storage account show -n <account> -g <rg> --query isHnsEnabled (should be true if you keep the override).
3. Re-check which storage account the connection string/account name+key actually resolves to — a staging/prod mix-up is common.
4. After fixing config, restart the app so the shell reloads settings.

Example fix

// before
options.UseHierarchicalNamespace = true; // account is NOT Gen2
// after
options.UseHierarchicalNamespace = false; // let the store detect capabilities
// OR create/use a Gen2 account:
// az storage account create -n myadlsgen2 -g rg --kind StorageV2 --enable-hierarchical-namespace true

var account = await armClient.GetStorageAccountResource(accountId).GetAsync();
bool hns = account.Value.Data.IsHnsEnabled == true;
if (options.UseHierarchicalNamespace == true && !hns)
{
    throw new InvalidOperationException(
        "UseHierarchicalNamespace=true requires a Gen2 (HNS) storage account.");
}

try
{
    await fileStore.GetDirectoryInfoAsync(path);
}
catch (FileStoreException ex) when (ex.Message.Contains("Hierarchical Namespace"))
{
    logger.LogCritical(ex, "Storage account is not Gen2 but HNS was claimed in config.");
    // fix options: set UseHierarchicalNamespace=false or move to a Gen2 account
}

When it happens

Trigger: Setting UseHierarchicalNamespace=true in BlobStorageOptions (or AzureBlobFileSystemOptions) while pointing at a standard Blob Storage (Gen1/flat-namespace) account. Thrown by any store operation that calls EnsureCapabilitiesAsync first: GetDirectoryInfoAsync, GetDirectoryContentByHierarchyAsync, GetDirectoryContentFlatAsync, TryCreateDirectoryAsync, TryDeleteDirectoryAsync, MoveFileAsync.

Common situations: Copying a connection string / account name from another environment where HNS was enabled; configuring the flag by hand after creating a normal (non-Gen2) storage account; misunderstanding that the flag must match the account's actual capability rather than turn it on.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Cannot create directory
• Cannot get file info with path
• Cannot get directory info with path
• Cannot get directory content with path
• Cannot create directory because the path

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/5b128ca07f76de59. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore/OrchardCore.FileStorage.AzureBlob/BlobFileStore.cs:119

        await _capabilitiesLock.WaitAsync();
        try
        {
            if (_capabilitiesInitialized)
            {
                return;
            }

            try
            {
                var accountInfo = await _blobServiceClient.GetAccountInfoAsync();
                var detectedHns = accountInfo.Value.IsHierarchicalNamespaceEnabled;

                if (_useHierarchicalNamespaceOverride.HasValue && _useHierarchicalNamespaceOverride.Value != detectedHns)
                {
                    if (_useHierarchicalNamespaceOverride.Value)
                    {
                        // Claiming Gen2 on a Gen1 account — DataLake API calls will fail at runtime.
                        throw new FileStoreException(
                            "'UseHierarchicalNamespace' is set to 'true' but the storage account does not have " +
                            "Hierarchical Namespace enabled. Correct the configuration or use a Gen2 storage account.");
                    }

                    // Override=false on a Gen2 account is safe but suboptimal.
                    _logger?.LogWarning(
                        "'UseHierarchicalNamespace' is set to 'false' but the storage account has Hierarchical Namespace enabled. " +
                        "Flat-namespace operations will be used, which means moves are not atomic and directory operations are less efficient. " +
                        "Remove the setting to use native Gen2 operations.");
                }

                var hnsEnabled = _useHierarchicalNamespaceOverride ?? detectedHns;
                _capabilities = new FileStoreCapabilities(
                    hasHierarchicalNamespace: hnsEnabled,
                    supportsAtomicMove: hnsEnabled);

                if (hnsEnabled)
                {

View on GitHub (pinned to 4306c0717f)