HNS Error

Overview

When logging in as an SFTP user via FileZilla, you may get this error:

Error: Connection timed out after 20 seconds of inactivity
Error: Could not connect to server

Normally, connection timeouts are due to network connectivity issues like NSG rules.

But this can also happen if the Blob storage account is configured with Hierarchical Namespace (HNS). Note: This problem only affects SFTP Gateway version 3.1.0.

The workaround is to migrate to a newer version of SFTP Gateway, or to use a Blob storage account that does not have HNS enabled.

What is Hierarchical Namespace (HNS)

HNS is a Blob storage account feature that lets you create empty subfolders. Normally, empty subfolders get pruned in Blob storage. But with HNS, they remain intact.

HNS can be enabled when creating a Blob storage account. But you cannot enable or disable HNS after a Blob storage account is already created.

You are able to find out if your storage account has hierarchical namespace enabled under Overview -> Properties -> Data Lake Storage.

The behavior of the problem

If you are running SFTP Gateway version 3.1.0 and connect to a Blob storage account with HNS enabled, it may work initially. But somewhere along the way, you will run into this error:

There will be a 20 second timeout, followed by an error message stating that the connection timed out after 20 seconds of inactivity.

The problem is that SFTP Gateway is unable to find the underlying file system for the SFTP user, so the timeout happens while initializing the session. And the file system is missing, because SFTP Gateway version 3.1.0 is unable to find the Blob storage endpoint for HNS-enabled Storage Accounts.

Note: The Blob storage account endpoint change is triggered by creating a new empty subfolder.

Solutions and workarounds

The best approach is to migrate to the latest version of SFTP Gateway. This issue is resolved in versions 3.1.1 and later.

One workaround would be to configure a new Blob Storage account that does not have HNS enabled.

Another workaround would be to use the existing HNS-enabled Blob Storage account. But make sure that you do not create any subfolders. This workaround is fragile, and is not recommended.