Azurite Azure Storage Emulator

3.35.0 verified Sat Apr 25 auth: no javascript

Azurite is an open-source, cross-platform Azure Storage API compatible server designed for local development. It emulates the behavior of Azure Blob, Queue, and Table storage services, allowing developers to test their applications without incurring costs or latency associated with cloud resources. The current stable version is 3.35.0, with minor releases occurring approximately every 1-3 months, typically bumping the supported Azure Storage API version and introducing new features or bug fixes. Key differentiators include its full compatibility with Azure Storage SDKs, support for all three major storage services (Blob, Queue, Table preview), and flexible deployment options via npm, Docker, or a VS Code extension. It is built on TypeScript and runs on Node.js, providing a consistent local environment for Azure Storage interactions.

Common errors

error HTTP 400 One of the request inputs is not valid or similar errors when submitting batch requests. ↓

cause An issue with HTTP header parsing in `SubmitBatch()` operations when a HTTP header value contained the HTTP header delimiter (`:`).

fix

This issue was resolved in Azurite v3.30.0. Update your Azurite instance to at least version 3.30.0 to fix batch request parsing.

error All subsequent requests failing with a 500 error after a client prematurely disconnects. ↓

cause An internal Azurite issue where premature client disconnections could lead to all following requests from any client failing with a 500 server error.

fix

This problem was fixed in Azurite v3.32.0. Upgrade your Azurite instance to version 3.32.0 or newer to prevent this cascading error state.

error Failure to delete a container after it was created with a blob, then deleted, and then recreated with the same name and a blob. ↓

cause An issue specific to SQL-backed persistence where container deletion was not fully reconciled, leading to conflicts on subsequent operations with the same name.

fix

This persistence logic bug was fixed in Azurite v3.35.0. Update your Azurite instance to at least version 3.35.0.

error Error: Cannot find module 'azurite' or similar module resolution failures when attempting to `import` or `require` Azurite. ↓

cause Azurite is distributed as a command-line executable and a server, not a JavaScript library designed for direct programmatic imports into application code.

fix

Do not attempt to import or require Azurite directly. Instead, run Azurite as a separate process (e.g., via child_process.spawn) or as a Docker container, and then interact with its HTTP endpoints using standard Azure Storage SDKs.

Warnings

breaking Telemetry data collection is enabled by default since Azurite v3.34.0. Users must explicitly disable it if not desired. ↓

fix Add the `--disableTelemetry` command-line option when starting Azurite via CLI, npm script, Docker, or programmatic spawn.

breaking Azurite V3 is a complete rewrite in TypeScript and is not directly compatible with configurations or APIs from the legacy Azurite V2. The legacy V2 code is on a separate branch and supports an older Azure Storage API version. ↓

fix Review the Azurite V3 documentation for updated command-line options and API versions. Migrate existing scripts and configurations to V3 specifics, as V2 options may not work or have different behavior.

gotcha By default, Azurite persists data to disk. For scenarios requiring ephemeral storage (e.g., CI/CD testing), explicit configuration is needed to avoid disk I/O. ↓

fix Start Azurite with the `--inMemoryPersistence` option. This will store all data in memory, ignoring the `--location` option for persistence.

gotcha Specific Shared Access Signature (SAS) permissions were not correctly enforced for some operations in versions prior to 3.28.0, potentially leading to unintended access. ↓

fix Upgrade Azurite to version 3.28.0 or newer to ensure correct SAS permission enforcement and maintain expected security boundaries.

breaking The Azure Storage API version supported by Azurite is periodically updated with new releases. Applications relying on specific older API versions might encounter unexpected behavior or errors if Azurite is updated past their targeted version. ↓

fix Regularly consult the Azurite version table in the README to ensure compatibility between your Azurite instance and the Azure Storage SDK version or REST API version your application targets.

Install

npm install azurite

yarn add azurite

pnpm add azurite

Imports

azurite
wrong
```
import { azurite } from 'azurite'
```
correct
```
N/A (run as CLI)
```
Azurite is primarily a command-line tool and server. It is not designed for direct programmatic import as a library within a Node.js application. To use it programmatically, spawn the 'azurite' executable as a child process.
AzuriteServer
wrong
```
import { AzuriteServer } from 'azurite'
```
correct
```
N/A (no public API)
```
Azurite does not expose a direct class or function for in-process server instantiation. It runs as an independent executable managed via CLI or Docker.
BlobServiceClient
wrong
```
import { BlobServiceClient } from 'azurite'
```
correct
```
N/A (use @azure/storage-blob)
```
While Azurite emulates Azure Storage, client SDKs (like BlobServiceClient for interacting with Blob storage) are provided by the official Azure SDKs (e.g., `@azure/storage-blob`), not Azurite itself.

Quickstart

Demonstrates how to programmatically start the Azurite local Azure Storage emulator server using Node.js `child_process`, configure its listening ports, data persistence, and disable telemetry, then listen for its output.

import { spawn } from 'child_process';
import path from 'path';

async function startAzuriteProgrammatically() {
  // Determine the Azurite command. Assumes global installation or local in node_modules/.bin
  const azuriteCommand = process.platform === 'win32'
    ? path.join(process.cwd(), 'node_modules', '.bin', 'azurite.cmd')
    : path.join(process.cwd(), 'node_modules', '.bin', 'azurite');

  // Fallback to global command if local not found (or if installed globally)
  const commandToExecute = require('which').sync(azuriteCommand, { nothrow: true }) || 'azurite';

  const azuriteProcess = spawn(commandToExecute, [
    '--blob', 'http://127.0.0.1:10000',
    '--queue', 'http://127.0.0.1:10001',
    '--table', 'http://127.0.0.1:10002',
    '--location', './azurite_data', // Persist data to a local directory
    '--debug', './azurite_debug.log', // Log debug info to a file
    '--silent', // Suppress console output from Azurite itself
    '--disableTelemetry' // Opt-out of telemetry data collection
  ]);

  azuriteProcess.stdout.on('data', (data) => {
    console.log(`Azurite stdout: ${data.toString()}`);
  });

  azuriteProcess.stderr.on('data', (data) => {
    console.error(`Azurite stderr: ${data.toString()}`);
  });

  azuriteProcess.on('error', (err) => {
    console.error(`Failed to start Azurite process: ${err.message}`);
  });

  azuriteProcess.on('close', (code) => {
    console.log(`Azurite process exited with code ${code}`);
  });

  console.log('Attempting to start Azurite. Waiting for services to become available...');
  await new Promise(resolve => setTimeout(resolve, 8000)); // Give Azurite time to start
  console.log('Azurite should be running on Blob (10000), Queue (10001), Table (10002).');
  console.log('Data will be persisted in ./azurite_data and debug logs in ./azurite_debug.log.');

  // To stop Azurite, you would typically use azuriteProcess.kill(); in a real application
  // For this quickstart, it will run until the Node.js script exits.
}

// You might need to 'npm install -g azurite' or 'npm install which' for this to run reliably.
// For local install: 'npm install azurite'
startAzuriteProgrammatically().catch(console.error);