{"id":13155,"library":"etcd3","title":"etcd3 Client for Node.js","description":"The `etcd3` library provides a robust, production-ready Node.js client for the etcd v3 API, which is based on Protocol Buffers. Currently at stable version `1.1.2`, the project demonstrates an active release cadence with frequent patch and minor updates, typically every few weeks to months. Key differentiators include comprehensive features such as intelligent load balancing, resilient fault handling with automatic reconnections (leveraging Cockatiel), atomic transactions, Software Transactional Memory (STM), high-level query builders, sophisticated lease management, real-time watchers, user and role administration, and leader election mechanisms. It also offers full type-safety for TypeScript users, ensuring a robust development experience, and is maintained by Microsoft.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/microsoft/etcd3","tags":["javascript","etcd3","etcd","node","client","protobuf","proto","typescript"],"install":[{"cmd":"npm install etcd3","lang":"bash","label":"npm"},{"cmd":"yarn add etcd3","lang":"bash","label":"yarn"},{"cmd":"pnpm add etcd3","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides fault handling and reconnection capabilities, as indicated by fixes related to its TypeScript types.","package":"cockatiel","optional":false}],"imports":[{"note":"While CommonJS `require` might work in older Node.js versions, `etcd3` officially supports Node.js >=16 and ships TypeScript types, favoring ESM `import` for modern usage.","wrong":"const { Etcd3 } = require('etcd3');","symbol":"Etcd3","correct":"import { Etcd3 } from 'etcd3';"},{"note":"This is a TypeScript interface for configuration options; use `import type` to prevent accidental runtime imports and ensure cleaner bundling.","wrong":"import { IOptions } from 'etcd3';","symbol":"IOptions","correct":"import type { IOptions } from 'etcd3';"},{"note":"Specific helper classes like `Lease`, `WatchBuilder`, `Election`, and `ComparatorBuilder` are named exports.","wrong":"const Lease = require('etcd3').Lease;","symbol":"Lease","correct":"import { Lease } from 'etcd3';"}],"quickstart":{"code":"import { Etcd3 } from 'etcd3';\n\nconst client = new Etcd3({\n  hosts: process.env.ETCD_ADDR ?? '127.0.0.1:2379' // Default etcd address\n});\n\n(async () => {\n  try {\n    console.log('Putting key \"foo\" with value \"bar\"...');\n    await client.put('foo').value('bar');\n    console.log('Key \"foo\" put successfully.');\n\n    const fooValue = await client.get('foo').string();\n    console.log('Retrieved \"foo\" value:', fooValue);\n\n    console.log('Fetching all keys starting with \"f\"...');\n    const allFValues = await client.getAll().prefix('f').keys();\n    console.log('All keys starting with \"f\":', allFValues);\n\n    console.log('Deleting all keys...');\n    await client.delete().all();\n    console.log('All keys deleted.');\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n  } finally {\n    client.close(); // Important to close the client connection\n  }\n})();","lang":"typescript","description":"This example initializes an `etcd3` client, connects to an etcd server, demonstrates putting and getting a key-value pair, querying keys with a prefix, and finally deleting all keys. It includes basic error handling and uses `ETCD_ADDR` for host configuration."},"warnings":[{"fix":"Upgrade to `etcd3@1.1.2` or newer to incorporate the fix.","message":"A race condition in `Host.resetAllServices` could lead to unexpected behavior during service resets.","severity":"gotcha","affected_versions":"<1.1.2"},{"fix":"Ensure all watcher event listener callbacks are robustly error-handled. Upgrade to `etcd3@1.1.0` or newer, which includes a fix to prevent this from affecting the underlying stream.","message":"User-defined errors within watcher event listeners could cause backoffs in the underlying gRPC stream, potentially leading to connection issues or missed events.","severity":"gotcha","affected_versions":"<1.1.0"},{"fix":"Upgrade to `etcd3@1.1.0` or newer for correct Buffer typings. For older versions, type assertions might be necessary, but this is not recommended.","message":"TypeScript typings for `Namespace.get(key)` incorrectly disallowed Buffer values, leading to type errors when attempting to retrieve binary data.","severity":"gotcha","affected_versions":"<1.1.0"},{"fix":"Upgrade to `etcd3@1.0.2` or newer, which includes an updated `cockatiel` version resolving these type conflicts.","message":"Incompatible TypeScript types with the `cockatiel` dependency could cause compilation issues in projects using strict type checking.","severity":"gotcha","affected_versions":"<1.0.2"},{"fix":"Ensure an etcd server is running and accessible. Set `export ETCD_ADDR=localhost:2379` (or your etcd host:port) before running applications or tests that connect to etcd.","message":"Running the official test suite or connecting to a non-default etcd server requires a running etcd instance and proper configuration via the `ETCD_ADDR` environment variable.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that your etcd server is running and listening on the expected host and port. Ensure the `ETCD_ADDR` environment variable or the `hosts` option in the `Etcd3` client constructor is correctly set to your etcd endpoint (e.g., '127.0.0.1:2379').","cause":"The etcd server is not running, is inaccessible from the client, or the configured host/port is incorrect.","error":"Error: 14 UNAVAILABLE: failed to connect to all addresses"},{"fix":"When using ES Modules (type: 'module' in package.json or .mjs files), use `import { Etcd3 } from 'etcd3';`. If using CommonJS, ensure your environment properly handles the module export or consider using `require('etcd3').Etcd3` if applicable, although ESM is preferred.","cause":"Attempting to use `const client = new Etcd3();` with CommonJS `require` syntax when `Etcd3` is primarily designed for ES Modules or when the import is incorrect.","error":"TypeError: Etcd3 is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}