{"record":{"id":"5b128ca07f76de59","repo":"OrchardCMS/OrchardCore","slug":"usehierarchicalnamespace-is-set-to-true-but-the-storage","errorCode":null,"errorMessage":"'UseHierarchicalNamespace' is set to 'true' but the storage account does not have Hierarchical Namespace enabled. Correct the configuration or use a Gen2 storage account.","messagePattern":"'UseHierarchicalNamespace' is set to 'true' but the storage account does not have Hierarchical Namespace enabled\\. Correct the configuration or use a Gen2 storage account\\.","errorType":"exception","errorClass":"FileStoreException","httpStatus":null,"severity":"critical","filePath":"src/OrchardCore/OrchardCore.FileStorage.AzureBlob/BlobFileStore.cs","lineNumber":119,"sourceCode":"        await _capabilitiesLock.WaitAsync();\n        try\n        {\n            if (_capabilitiesInitialized)\n            {\n                return;\n            }\n\n            try\n            {\n                var accountInfo = await _blobServiceClient.GetAccountInfoAsync();\n                var detectedHns = accountInfo.Value.IsHierarchicalNamespaceEnabled;\n\n                if (_useHierarchicalNamespaceOverride.HasValue && _useHierarchicalNamespaceOverride.Value != detectedHns)\n                {\n                    if (_useHierarchicalNamespaceOverride.Value)\n                    {\n                        // Claiming Gen2 on a Gen1 account — DataLake API calls will fail at runtime.\n                        throw new FileStoreException(\n                            \"'UseHierarchicalNamespace' is set to 'true' but the storage account does not have \" +\n                            \"Hierarchical Namespace enabled. Correct the configuration or use a Gen2 storage account.\");\n                    }\n\n                    // Override=false on a Gen2 account is safe but suboptimal.\n                    _logger?.LogWarning(\n                        \"'UseHierarchicalNamespace' is set to 'false' but the storage account has Hierarchical Namespace enabled. \" +\n                        \"Flat-namespace operations will be used, which means moves are not atomic and directory operations are less efficient. \" +\n                        \"Remove the setting to use native Gen2 operations.\");\n                }\n\n                var hnsEnabled = _useHierarchicalNamespaceOverride ?? detectedHns;\n                _capabilities = new FileStoreCapabilities(\n                    hasHierarchicalNamespace: hnsEnabled,\n                    supportsAtomicMove: hnsEnabled);\n\n                if (hnsEnabled)\n                {","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/OrchardCMS/OrchardCore/blob/4306c0717fe573f6fca1b4955909ddab6a192807/src/OrchardCore/OrchardCore.FileStorage.AzureBlob/BlobFileStore.cs#L101-L137","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Verify the account with: az storage account show -n <account> -g <rg> --query isHnsEnabled (should be true if you keep the override).","Re-check which storage account the connection string/account name+key actually resolves to — a staging/prod mix-up is common.","After fixing config, restart the app so the shell reloads settings."],"exampleFix":"// before\noptions.UseHierarchicalNamespace = true; // account is NOT Gen2\n// after\noptions.UseHierarchicalNamespace = false; // let the store detect capabilities\n// OR create/use a Gen2 account:\n// az storage account create -n myadlsgen2 -g rg --kind StorageV2 --enable-hierarchical-namespace true","handlingStrategy":"validation","validationCode":"var account = await armClient.GetStorageAccountResource(accountId).GetAsync();\nbool hns = account.Value.Data.IsHnsEnabled == true;\nif (options.UseHierarchicalNamespace == true && !hns)\n{\n    throw new InvalidOperationException(\n        \"UseHierarchicalNamespace=true requires a Gen2 (HNS) storage account.\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    await fileStore.GetDirectoryInfoAsync(path);\n}\ncatch (FileStoreException ex) when (ex.Message.Contains(\"Hierarchical Namespace\"))\n{\n    logger.LogCritical(ex, \"Storage account is not Gen2 but HNS was claimed in config.\");\n    // fix options: set UseHierarchicalNamespace=false or move to a Gen2 account\n}","preventionTips":["Never hardcode UseHierarchicalNamespace=true; leave it unset/null so capabilities are auto-detected.","Provision Gen2 accounts with --enable-hierarchical-namespace true when DataLake features are needed.","Verify with 'az storage account show --query isHnsEnabled' when copying settings between environments.","Add a config validation step at startup that fails fast on this mismatch."],"tags":["azure","blob-storage","config","data-lake-gen2","invalid-config-value"],"backgroundTag":"invalid-config-value","analyzedSha":"4306c0717fe573f6fca1b4955909ddab6a192807","analyzedAt":"2026-09-13T17:41:05.024Z","contentChangedAt":"2026-09-13T17:41:05.024Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}