n8n-io/n8n · error · UnexpectedError

Request to Azure Blob storage failed: ${error.message}

Error message

Request to Azure Blob storage failed: ${error.message}

What it means

UnexpectedError thrown by AzureBlobService.handleError, the catch-all for every Azure SDK error that is not specifically handled (e.g. non-404 in checkConnection, or any failure in put/get/getMetadata/delete). It wraps the original via ensureError and preserves it as cause. The original provider message is appended for diagnosis.

Source

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

			if (fileName) metadata.fileName = decodeURIComponent(fileName);

			return metadata;
		} catch (e) {
			this.handleError(e);
		}
	}

	async delete(blobName: string) {
		try {
			await this.containerClient.getBlockBlobClient(blobName).deleteIfExists();
		} catch (e) {
			this.handleError(e);
		}
	}

	private handleError(e: unknown): never {
		const error = ensureError(e);
		throw new UnexpectedError(`Request to Azure Blob storage failed: ${error.message}`, {
			cause: error,
		});
	}
}

View on GitHub (pinned to 5ac6606e81)

Solutions

Read the wrapped message — it includes the underlying Azure error text (auth, throttling, DNS, etc.).
For 403, rotate and re-set N8N_EXTERNAL_STORAGE_AZURE_ACCOUNT_KEY / connection string.
For timeouts/throttling, check network egress and Azure subscription limits.
Verify the n8n host clock is in sync (shared-key auth is time-sensitive).

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight connectivity check before relying on the service
await azureBlobService.init(); // surfaces auth/network issues at startup

Type guard

import { UnexpectedError } from 'n8n-workflow';
const isAzureFailure = (e: unknown): boolean =>
  e instanceof UnexpectedError && /Request to Azure Blob storage failed/.test(e.message);

Try / catch

try {
  await azureBlobService.put(blobName, body);
} catch (e) {
  if (e instanceof UnexpectedError && /Request to Azure Blob storage failed/.test(e.message)) {
    const cause = (e as any).cause;
    // classify cause.statusCode: 403 -> rotate key, 503 -> throttle/backoff
  }
  throw e;
}

Prevention

Call init() at startup to catch auth/network issues early.
Rotate storage keys on a schedule and update env vars atomically.
Keep the n8n host clock synced (shared-key signing is time-sensitive).

When it happens

Trigger: Any Azure storage operation (put/get/getMetadata/delete, or checkConnection with a non-404 status) throws and falls through to handleError. Typical sources: 403 auth failure, network timeout, throttling (503), SDK serialization error, or a corrupted credential.

Common situations: Expired or rotated storage key / SAS; network firewall blocking blob.core.windows.net; Azure throttling under high load; accountKey / connectionString mismatch; clock skew breaking shared-key signing.

Related errors

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