n8n-io/n8n · critical · UserError

Azure Blob container name not configured. Please set `N8N_EX

Error message

Azure Blob container name not configured. Please set `N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME`.

What it means

UserError thrown in the AzureBlobService constructor when config.containerName === ''. The container name is sourced from N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME. Without it the service cannot construct a ContainerClient, so it fails fast at DI time rather than producing confusing per-request errors later.

Source

Thrown at packages/@n8n/blob-storage/src/azure-blob/azure-blob.service.ee.ts:25

import { UnexpectedError, UserError } from 'n8n-workflow';
import { PassThrough, Readable, pipeline } from 'node:stream';

import { AzureBlobConfig } from './azure-blob.config';
import { createFixedSizeChunker } from '../stream-utils';
import type { BlobMetadata, PreWriteBlobMetadata } from '../types';

@Service()
export class AzureBlobService {
	private readonly containerClient: ContainerClient;

	private isReady = false;

	constructor(
		private readonly logger: Logger,
		private readonly config: AzureBlobConfig,
	) {
		if (config.containerName === '') {
			throw new UserError(
				'Azure Blob container name not configured. Please set `N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME`.',
			);
		}
		this.containerClient = this.buildContainerClient();
	}

	private buildContainerClient(): ContainerClient {
		const { connectionString, accountName, accountKey, containerName, endpoint, authAutoDetect } =
			this.config;

		if (connectionString) {
			return BlobServiceClient.fromConnectionString(connectionString).getContainerClient(
				containerName,
			);
		}

		const url = endpoint || `https://${accountName}.blob.core.windows.net`;
		const serviceClient = authAutoDetect

View on GitHub (pinned to 5ac6606e81)

Solutions

Set N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME to an existing Azure container name.
Confirm the env var is actually exported in the process running n8n (printenv in the same shell).
If Azure is not intended, switch N8N_EXTERNAL_STORAGE_MODE back to filesystem (or s3).
Restart n8n after setting the variable so the DI container re-constructs the service.

Example fix

# before
N8N_EXTERNAL_STORAGE_MODE=azure
# container name missing

# after
N8N_EXTERNAL_STORAGE_MODE=azure
N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME=my-n8n-blobs

Defensive patterns

Strategy: validation

Validate before calling

function assertAzureConfig(env: NodeJS.ProcessEnv) {
  if (env.N8N_EXTERNAL_STORAGE_MODE === 'azure' && !env.N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME) {
    throw new Error('N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME must be set when mode=azure');
  }
}

Type guard

const hasAzureContainer = (env: NodeJS.ProcessEnv): boolean =>
  !!env.N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME && env.N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME.length > 0;

Try / catch

try {
  await azureBlobService.init();
} catch (e) {
  if (e instanceof UserError && /container name not configured/.test(e.message)) {
    // halt startup with a clear config-missing message
  }
  throw e;
}

Prevention

Validate required env vars in a pre-startup checklist before DI constructs services.
Document the full set of N8N_EXTERNAL_STORAGE_AZURE_* variables in the deployment template.
Run a config smoke test in CI against the production env file.

When it happens

Trigger: AzureBlobService is instantiated (via @n8n/di during startup) while N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME is unset or empty AND external blob storage mode is set to azure. The constructor check at line 24 throws before any Azure call is attempted.

Common situations: Enabling N8N_EXTERNAL_STORAGE_MODE=azure without setting the container name env var; a typo in the env var name; a deployment template that omits the variable; CI that copies a partial env file.

Related errors

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/abdb784d2cb4b740. Report an issue: GitHub.