@azure/storage-blob
| Property | Value |
|---|---|
| Package | @azure/storage-blob |
| Versions Covered | >=12.0.0 |
| Contract Version | 1.0.0 |
| Status | production |
| Last Verified | 2026-02-27 |
| Maintainer | corpus-team |
Installation
npm install @azure/storage-blob
Covered Functions
This contract covers 9 function(s):
download()
Downloads a blob from Azure Blob Storage
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.download(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: blob exists and download succeeds
Returns:
BlobDownloadResponse with readableStreamBody and blob metadata
📖 Source
🔴 ERROR - blob-not-found
Condition: blob does not exist
Throws: RestError with statusCode 404 and x-ms-error-code: BlobNotFound
Required Handling:
Caller MUST catch RestError and check error.statusCode === 404 or error.response.headers.get('x-ms-error-code') === 'BlobNotFound' to handle missing blobs.
📖 Source
🔴 ERROR - blob-archived
Condition: blob is in archived tier
Throws: RestError with statusCode 409 and errorCode: BlobArchived
Required Handling:
Caller MUST catch RestError and handle archived blobs by either rehydrating the blob first or returning appropriate error to user.
📖 Source
🔴 ERROR - network-error
Condition: network failure, connection timeout, or DNS resolution failure
Throws: Error with code ECONNREFUSED, ETIMEDOUT, or ENOTFOUND
Required Handling:
Caller MUST catch errors and implement retry logic with exponential backoff for transient network failures.
📖 Source
getProperties()
Gets blob properties including metadata, content type, and last modified time
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.getProperties(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: blob exists
Returns:
BlobGetPropertiesResponse with metadata, contentType, lastModified, etc.
📖 Source
🔴 ERROR - blob-not-found
Condition: blob does not exist
Throws: RestError with statusCode 404 and errorCode: BlobNotFound
Required Handling:
Caller MUST catch RestError and check error.statusCode === 404 to handle missing blobs. Common pattern is to check existence before accessing properties.
📖 Source
🔴 ERROR - container-not-found
Condition: container does not exist
Throws: RestError with statusCode 404 and errorCode: ContainerNotFound
Required Handling:
Caller MUST catch RestError and distinguish between BlobNotFound and ContainerNotFound to provide appropriate error messages.
📖 Source
upload()
Uploads data to a block blob
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.upload(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: upload succeeds
Returns:
BlockBlobUploadResponse with requestId, version, and ETag
📖 Source
🔴 ERROR - blob-already-exists
Condition: blob exists and If-None-Match: * is set
Throws: RestError with statusCode 409 and errorCode: BlobAlreadyExists
Required Handling:
Caller MUST catch RestError and check error.statusCode === 409 to handle conflicts when blob already exists.
📖 Source
🔴 ERROR - container-not-found
Condition: container does not exist
Throws: RestError with statusCode 404 and errorCode: ContainerNotFound
Required Handling:
Caller MUST catch RestError and either create container first or return appropriate error. Common mistake is not checking container existence.
📖 Source
🔴 ERROR - invalid-blob-type
Condition: blob exists as different type (e.g., page blob)
Throws: RestError with statusCode 409 and errorCode: InvalidBlobType
Required Handling:
Caller MUST catch RestError and handle type conflicts appropriately.
📖 Source
🔴 ERROR - network-error
Condition: network failure during upload
Throws: Error with code ECONNREFUSED, ETIMEDOUT, or ENOTFOUND
Required Handling:
Caller MUST catch errors and implement retry logic for transient failures.
📖 Source
uploadFile()
Uploads a local file to a block blob (Node.js only)
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.uploadFile(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: file upload succeeds
Returns:
BlobUploadCommonResponse with requestId, version, and ETag
📖 Source
🔴 ERROR - container-not-found
Condition: container does not exist
Throws: RestError with statusCode 404 and errorCode: ContainerNotFound
Required Handling:
Caller MUST catch RestError and create container before uploading.
📖 Source
🔴 ERROR - network-error
Condition: network failure during multipart upload
Throws: Error with network error code
Required Handling:
Caller MUST catch errors and retry failed uploads with exponential backoff.
📖 Source
uploadData()
Uploads a Buffer or Blob to a block blob
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.uploadData(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: data upload succeeds
Returns:
BlobUploadCommonResponse with requestId, version, and ETag
📖 Source
🔴 ERROR - container-not-found
Condition: container does not exist
Throws: RestError with statusCode 404 and errorCode: ContainerNotFound
Required Handling:
Caller MUST catch RestError and handle missing container appropriately.
📖 Source
🔴 ERROR - network-error
Condition: network failure
Throws: Error with network error code
Required Handling:
Caller MUST catch errors and implement retry logic.
📖 Source
create()
Creates a new container in the storage account
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.create(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: container creation succeeds
Returns:
ContainerCreateResponse with requestId and ETag
📖 Source
🔴 ERROR - container-already-exists
Condition: container with same name already exists
Throws: RestError with statusCode 409 and errorCode: ContainerAlreadyExists
Required Handling:
Caller MUST catch RestError and check error.statusCode === 409 to handle existing containers. Common pattern is to check exists() first or catch and continue.
📖 Source
🔴 ERROR - container-being-deleted
Condition: container is currently being deleted
Throws: RestError with statusCode 409 and errorCode: ContainerBeingDeleted
Required Handling:
Caller MUST catch RestError and wait for deletion to complete before retrying.
📖 Source
🔴 ERROR - auth-error
Condition: authentication fails or insufficient permissions
Throws: RestError with statusCode 403
Required Handling:
Caller MUST catch RestError with statusCode 403 and handle authentication/authorization failures.
📖 Source
delete()
Deletes the container
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.delete(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: container deletion succeeds
Returns:
ContainerDeleteResponse with requestId
📖 Source
🔴 ERROR - container-not-found
Condition: container does not exist
Throws: RestError with statusCode 404 and errorCode: ContainerNotFound
Required Handling:
Caller MUST catch RestError and handle missing containers. Common pattern is to check exists() first or catch 404 and treat as success.
📖 Source
🔴 ERROR - lease-id-missing
Condition: container has active lease but lease ID not provided
Throws: RestError with statusCode 412 and errorCode: LeaseIdMissing
Required Handling:
Caller MUST catch RestError with statusCode 412 and handle lease conflicts.
📖 Source
exists()
Checks whether the container exists
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.exists(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: check completes successfully
Returns:
boolean indicating whether container exists
📖 Source
⚠️ WARNING - auth-error
Condition: authentication fails
Throws: RestError with statusCode 403
Required Handling:
Caller SHOULD catch RestError for permission errors even when checking existence.
📖 Source
listContainers()
Lists containers in the storage account
Import:
import @azure/storage-blob from '@azure/storage-blob';
@azure/storage-blob.listContainers(...);
Postconditions
What happens after calling this function:
ℹ️ INFO - success
Condition: listing succeeds
Returns:
AsyncIterableIterator of ContainerItem objects
📖 Source
🔴 ERROR - auth-error
Condition: authentication fails
Throws: RestError with statusCode 403
Required Handling:
Caller MUST catch RestError when iterating containers to handle auth failures.
📖 Source
Example: Proper Error Handling
import storage-blob from '@azure/storage-blob';
async function example() {
try {
const result = await download(/* args */);
// Handle success
return result;
} catch (error) {
// Handle error according to contract postconditions
console.error('Error:', error);
throw error;
}
}