microsoft/garnet · critical · InvalidAzureConfiguration

Cannot use AzureStorage device without supplying storage-str

Error message

Cannot use AzureStorage device without supplying storage-string or storage-service-uri

What it means

InvalidAzureConfiguration thrown during Options.Initialize when the device type is AzureStorage but neither AzureStorageConnectionString nor AzureStorageServiceUri is provided. The Azure storage device factory needs at least one credential source; with neither, it cannot authenticate. This is a startup configuration guard that fires before any network listener is created.

Source

Thrown at libs/host/Configuration/Options.cs:755

            return isValid;
        }

        public GarnetServerOptions GetServerOptions(ILogger logger = null)
        {
            var enableStorageTier = EnableStorageTier.GetValueOrDefault();
            var enableRevivification = EnableRevivification.GetValueOrDefault();

            if (UseNativeDeviceLinux.GetValueOrDefault())
            {
                logger?.LogWarning("The --use-native-device-linux option is deprecated. Please use --device-type Native instead.");
                DeviceType = DeviceType.Native;
            }

            var deviceType = GetDeviceType(logger);

            var useAzureStorage = deviceType == DeviceType.AzureStorage;
            if (useAzureStorage && string.IsNullOrEmpty(AzureStorageConnectionString) && string.IsNullOrEmpty(AzureStorageServiceUri))
                throw new InvalidAzureConfiguration("Cannot use AzureStorage device without supplying storage-string or storage-service-uri");
            if (useAzureStorage && !string.IsNullOrEmpty(AzureStorageConnectionString) && !string.IsNullOrEmpty(AzureStorageServiceUri))
                throw new InvalidAzureConfiguration("Cannot use AzureStorage device with both storage-string and storage-service-uri");

            var logDir = LogDir;
            if (!useAzureStorage && enableStorageTier) logDir = new DirectoryInfo(string.IsNullOrEmpty(logDir) ? "." : logDir).FullName;
            var checkpointDir = CheckpointDir;
            if (!useAzureStorage) checkpointDir = new DirectoryInfo(string.IsNullOrEmpty(checkpointDir) ? (string.IsNullOrEmpty(logDir) ? "." : logDir) : checkpointDir).FullName;

            if (!Format.TryParseAddressList(Address, Port, out var endpoints, out _, ProtectedMode == CommandLineBooleanOption.True)
              || endpoints.Length == 0)
                throw new GarnetException($"Invalid endpoint format {Address} {Port}.");

            EndPoint[] clusterAnnounceEndpoint = null;
            if (ClusterAnnounceIp != null)
            {
                ClusterAnnouncePort = ClusterAnnouncePort == 0 ? Port : ClusterAnnouncePort;
                clusterAnnounceEndpoint = Format.TryCreateEndpoint(ClusterAnnounceIp, ClusterAnnouncePort, tryConnect: false, logger: logger);
                if (clusterAnnounceEndpoint == null || !endpoints.Any(endpoint =>

View on GitHub (pinned to 951b0fc683)

Solutions

1. Provide either --storage-string with a valid Azure Storage connection string, or --storage-service-uri with a blob service URI (used with managed identity).
2. Verify the environment variable or config field feeding AzureStorageConnectionString is populated in the deployment environment.
3. If using managed identity, set AzureStorageServiceUri (and optionally AzureStorageManagedIdentity) and leave the connection string empty.
4. If Azure storage is not actually needed, switch device-type back to local (e.g., Native or Emulated).

Example fix

// before
options.DeviceType = DeviceType.AzureStorage;
// no storage-string or service-uri set

// after
options.DeviceType = DeviceType.AzureStorage;
options.AzureStorageConnectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONN_STRING");

void ValidateAzureConfig(Options opts)
{
    var useAzure = opts.DeviceType == DeviceType.AzureStorage;
    if (useAzure && string.IsNullOrEmpty(opts.AzureStorageConnectionString) && string.IsNullOrEmpty(opts.AzureStorageServiceUri))
        throw new InvalidOperationException("AzureStorage device requires --storage-string or --storage-service-uri.");
}

try
{
    options.Initialize(logger);
}
catch (InvalidAzureConfiguration ex)
{
    logger.LogCritical(ex, "Azure storage configuration is incomplete. Set the storage connection string or service URI.");
    throw;
}

When it happens

Trigger: Setting --device-type AzureStorage (or DeviceType = DeviceType.AzureStorage) in the Options without supplying --storage-string (AzureStorageConnectionString) or --storage-service-uri (AzureStorageServiceUri). Typical in cloud deployments where the connection string is expected from an environment variable or key vault that was not wired up.

Common situations: Deploying to Azure with device-type AzureStorage but forgetting to set the storage connection string env var; key vault reference not resolved; managed identity intended but the service-URI option used instead was also omitted; copy-paste config that dropped the storage-string line.

Related errors

• Cannot use AzureStorage device with both storage-string and
• Invalid endpoint format {Address} {Port}.
• Cluster announce endpoint does not match list of listen endp
• Gossip sample fraction should be in range [0,100]
• Azure Storage connection string is required to read/write to

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/e4995fb25249f23b. Report an issue: GitHub.