VictoriaMetrics/VictoriaMetrics · error

missing AZURE_STORAGE_ACCOUNT_NAME environment variable when

Error message

missing AZURE_STORAGE_ACCOUNT_NAME environment variable when AZURE_USE_DEFAULT_CREDENTIAL=true is set; see https://docs.victoriametrics.com/victoriametrics/vmbackup/#providing-credentials-via-env-variables

What it means

Raised by azremote/azblob.go newClient() when AZURE_USE_DEFAULT_CREDENTIAL=true is set but AZURE_STORAGE_ACCOUNT_NAME is empty. Default Azure credentials authenticate the caller, but the client still needs the storage account name to build the service URL (https://<account>.<domain>/). The library refuses to guess the account, so FS.Init() fails and no backup can proceed.

Source

Thrown at lib/backup/azremote/azblob.go:114

		creds, err := azblob.NewSharedKeyCredential(accountName, accountKey)
		if err != nil {
			return nil, fmt.Errorf("failed to create Shared Key credentials: %w", err)
		}
		serviceURL := fs.getServiceURL(accountName)
		return service.NewClientWithSharedKeyCredential(serviceURL, creds, nil)
	}

	useDefault := fs.env("AZURE_USE_DEFAULT_CREDENTIAL")
	if useDefault == "true" {
		logger.Infof("creating AZBlob service client from default credentials")
		creds, err := azidentity.NewDefaultAzureCredential(nil)
		if err != nil {
			return nil, fmt.Errorf("failed to create default Azure credentials: %w", err)
		}

		accountName := fs.env("AZURE_STORAGE_ACCOUNT_NAME")
		if accountName == "" {
			return nil, fmt.Errorf("missing AZURE_STORAGE_ACCOUNT_NAME environment variable when AZURE_USE_DEFAULT_CREDENTIAL=true is set; " +
				"see https://docs.victoriametrics.com/victoriametrics/vmbackup/#providing-credentials-via-env-variables")
		}

		serviceURL := fs.getServiceURL(accountName)
		return service.NewClient(serviceURL, creds, nil)
	}

	return nil, fmt.Errorf("failed to detect credentials for AZBlob; ensure that one of the options listed at " +
		"https://docs.victoriametrics.com/victoriametrics/vmbackup/#providing-credentials-via-env-variables is set")
}

func (fs *FS) env(name string) string {
	if fs.envLookupFunc != nil {
		v, _ := fs.envLookupFunc(name)
		return v
	}
	v, _ := envtemplate.LookupEnv(name)
	return v

View on GitHub (pinned to 5079fb58f1)

Solutions

1. Set AZURE_STORAGE_ACCOUNT_NAME to the storage account that hosts the backup container before starting the backup.
2. If using envtemplate syntax, verify the referenced variable (e.g. ${AZURE_STORAGE_ACCOUNT_NAME}) is actually populated in the process environment.
3. Check the process environment the backup runs with (systemd EnvironmentFile=, docker -e / k8s env) — not just the interactive shell.
4. Alternatively switch to AZURE_STORAGE_ACCOUNT_CONNECTION_STRING, which embeds both account name and key.

Example fix

// before
AZURE_USE_DEFAULT_CREDENTIAL=true   # account name missing

// after
export AZURE_USE_DEFAULT_CREDENTIAL=true
export AZURE_STORAGE_ACCOUNT_NAME=mystorageacct

if os.Getenv("AZURE_USE_DEFAULT_CREDENTIAL") == "true" && os.Getenv("AZURE_STORAGE_ACCOUNT_NAME") == "" {
	return errors.New("AZURE_STORAGE_ACCOUNT_NAME must be set when AZURE_USE_DEFAULT_CREDENTIAL=true")
}

if err := fs.Init(ctx); err != nil {
	if strings.Contains(err.Error(), "AZURE_STORAGE_ACCOUNT_NAME") {
		return fmt.Errorf("config: %w (set AZURE_STORAGE_ACCOUNT_NAME in the service environment)", err)
	}
	return err
}

When it happens

Trigger: AZURE_USE_DEFAULT_CREDENTIAL=true exported, but AZURE_STORAGE_ACCOUNT_NAME missing, empty after envtemplate expansion (e.g. it references an unset ${VAR} placeholder), or set only in a shell/profile that the backup process does not inherit (systemd unit, container, cron).

Common situations: Containerized vmbackup where env vars were defined in the host shell but not passed into the container; systemd services with a stale EnvironmentFile; mis-typed variable name (e.g. AZURE_STORAGE_ACCOUNT instead of AZURE_STORAGE_ACCOUNT_NAME); config template expanding to empty string.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• failed to create default Azure credentials: %w
• failed to detect credentials for AZBlob; ensure that one of
• cannot list blobs at %s (remote path %q): %w
• unexpected prefix for AZBlob key %q; want %q
• cannot delete `backup complete` file at %s: %w

AI-assisted analysis of VictoriaMetrics/VictoriaMetrics@5079fb58f1 (2026-09-03). Data as JSON: /api/errors/db4b307d221d0188. Report an issue: GitHub.