{"id":17381,"library":"taskcluster-client","title":"Taskcluster Client for JavaScript","description":"taskcluster-client is the official JavaScript client library for interfacing with Taskcluster components, providing a comprehensive asynchronous interface for all Taskcluster API methods. Primarily designed for server-side Node.js applications, it is deeply integrated into the Taskcluster ecosystem for inter-service communication. The current stable version, as per recent releases, is v99.1.1. The package maintains an active release cadence, frequently incorporating patch and minor updates that include critical Node.js (currently requiring v24.15.0 or later) and Go security upgrades, along with enhancements to worker deployment and monitoring. Key differentiators include robust retry mechanisms for transient network errors and flexible authentication options supporting both environment variables and direct credential provision, ensuring secure and reliable interaction with Taskcluster services.","status":"active","version":"87.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/taskcluster/taskcluster#main","tags":["javascript"],"install":[{"cmd":"npm install taskcluster-client","lang":"bash","label":"npm"},{"cmd":"yarn add taskcluster-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add taskcluster-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment for server-side JS operations.","package":"node","optional":false}],"imports":[{"note":"The primary entry point, providing access to all client classes like `Queue`, `Auth`, etc., as properties of the default export. ES module import is preferred.","wrong":"const taskcluster = require('taskcluster-client');","symbol":"taskcluster","correct":"import taskcluster from 'taskcluster-client';"},{"note":"Client classes like `Queue` and `Auth` are accessed as properties of the `taskcluster` default export, not as named exports from the root module.","wrong":"import { Queue } from 'taskcluster-client';","symbol":"QueueClient","correct":"import taskcluster from 'taskcluster-client';\nconst queue = new taskcluster.Queue(...);"},{"note":"`fromEnvVars` is a utility function available on the `taskcluster` default export for convenient credential and root URL loading from standard Taskcluster environment variables.","wrong":"import { fromEnvVars } from 'taskcluster-client';","symbol":"fromEnvVars","correct":"import taskcluster from 'taskcluster-client';\nconst config = taskcluster.fromEnvVars();"}],"quickstart":{"code":"import taskcluster from 'taskcluster-client';\nimport { URL } from 'url';\n\n// Load credentials from environment variables, or specify directly\nconst clientOptions = {\n  ...taskcluster.fromEnvVars(),\n  // Override rootUrl if TASKCLUSTER_PROXY_URL is desired in a task\n  rootUrl: process.env.TASKCLUSTER_PROXY_URL || 'https://taskcluster.net',\n  credentials: {\n    clientId: process.env.TASKCLUSTER_CLIENT_ID || '',\n    accessToken: process.env.TASKCLUSTER_ACCESS_TOKEN || '',\n    certificate: process.env.TASKCLUSTER_CERTIFICATE ? JSON.parse(process.env.TASKCLUSTER_CERTIFICATE) : undefined\n  },\n  timeout: 60 * 1000, // 60-second timeout per request\n  retries: 3\n};\n\n// Instantiate the Queue Client class\nconst queue = new taskcluster.Queue(clientOptions);\n\nasync function listTasks() {\n  try {\n    console.log(`Attempting to list tasks from ${clientOptions.rootUrl}...`);\n    // For this example, we'll try to get the latest 10 tasks.\n    // Note: 'listTasks' often requires appropriate scopes and context.\n    const { tasks } = await queue.listLatestTasks({ limit: 10 });\n    console.log(`Successfully retrieved ${tasks.length} tasks.`);\n    for (const task of tasks) {\n      console.log(`  Task ID: ${task.taskId}, State: ${task.state}`);\n    }\n  } catch (error) {\n    console.error('Failed to list tasks:', error.message);\n    if (error.statusCode === 401 || error.statusCode === 403) {\n      console.error('Check your Taskcluster credentials and scopes.');\n    }\n  }\n}\n\nlistTasks();\n","lang":"typescript","description":"This quickstart demonstrates how to instantiate a Taskcluster client, configure it with credentials (from env vars or directly), and use the Queue service to list recent tasks. It highlights error handling for common authentication issues."},"warnings":[{"fix":"Consult the Taskcluster documentation for the new `taskcluster/websocktunnel` Docker image tagging scheme and update your Dockerfile or deployment configurations accordingly.","message":"The `taskcluster/websocktunnel` Docker image tags underwent a breaking change. Users relying on specific tags for this image may need to update their configurations.","severity":"breaking","affected_versions":">=99.0.0"},{"fix":"Review any Taskcluster task definitions that use absolute paths in `mounts` or artifact `path` properties. Ensure they are compatible with the corrected path evaluation behavior. Adjust paths if they were inadvertently relying on the previous incorrect behavior.","message":"Generic Worker now correctly evaluates absolute paths within `mounts` (properties `directory` and `file`) and artifacts (property `path`). Previously, Generic Worker effectively stripped these absolute paths, leading to incorrect file resolution.","severity":"breaking","affected_versions":">=98.0.0"},{"fix":"When using `taskcluster.fromEnvVars()` inside a Taskcluster task that should use the proxy, explicitly set the `rootUrl` option to `process.env.TASKCLUSTER_PROXY_URL` in your client instantiation, e.g., `new taskcluster.Auth({ ...taskcluster.fromEnvVars(), rootUrl: process.env.TASKCLUSTER_PROXY_URL })`.","message":"The `taskcluster.fromEnvVars()` utility function does not respect the `TASKCLUSTER_PROXY_URL` environment variable. If you are running client code within a Taskcluster task that needs to communicate via the proxy, manually set `rootUrl`.","severity":"gotcha","affected_versions":">=87.0.0"},{"fix":"Regularly check the latest changelogs and `engines` field in `package.json` for the required Node.js version. Upgrade your Node.js runtime environment to meet the latest requirements (currently Node.js v24.15.0 for v99.1.1).","message":"This library frequently updates its required Node.js version, often including security updates. Running with an older Node.js version can lead to compatibility issues or missed security patches.","severity":"gotcha","affected_versions":">=87.0.0"},{"fix":"Upgrade to `taskcluster-client` v99.1.1 or newer. For affected deployments, manually verify and deprovision any Azure resources that correspond to stuck workers.","message":"Azure provider workers were previously getting stuck in `STOPPING` indefinitely if their backing Azure resources were deleted out-of-band. While fixed in v99.1.1, older versions will exhibit this behavior, causing resource leaks or stalled deployments.","severity":"breaking","affected_versions":"<99.1.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `credentials.clientId` and `credentials.accessToken` are correctly provided and the associated client has the necessary scopes for the API calls being made. For temporary credentials, also verify `credentials.certificate`.","cause":"Missing or incorrect `clientId` or `accessToken`, or insufficient scopes assigned to the credentials.","error":"Error: Failed to list tasks: Unauthorized (401)"},{"fix":"Verify that the `rootUrl` is correct and the Taskcluster instance it points to is accessible from where your client code is running. Check network connectivity or firewall rules.","cause":"The `rootUrl` provided is incorrect or the Taskcluster instance is unreachable/down.","error":"Failed to list tasks: connect ECONNREFUSED <host>:<port>"},{"fix":"For operations involving large artifacts (e.g., GitHub service log streaming), ensure your `taskcluster-client` version is up-to-date (>=98.0.1) as recent versions include fixes to stream artifacts rather than downloading them entirely into memory. For custom logic, implement streaming where possible.","cause":"Processing very large log artifacts or other large data streams entirely in memory without streaming.","error":"Error: OutOfMemoryError: JavaScript heap out of memory"}],"ecosystem":"npm","meta_description":null}