Taskcluster Client for JavaScript

Common errors

• Error: Failed to list tasks: Unauthorized (401)

  cause Missing or incorrect `clientId` or `accessToken`, or insufficient scopes assigned to the credentials.
  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`.

• Failed to list tasks: connect ECONNREFUSED <host>:<port>

  cause The `rootUrl` provided is incorrect or the Taskcluster instance is unreachable/down.
  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.

• Error: OutOfMemoryError: JavaScript heap out of memory

  cause Processing very large log artifacts or other large data streams entirely in memory without streaming.
  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.

Warnings

• breaking The `taskcluster/websocktunnel` Docker image tags underwent a breaking change. Users relying on specific tags for this image may need to update their configurations.
  Fix: Consult the Taskcluster documentation for the new `taskcluster/websocktunnel` Docker image tagging scheme and update your Dockerfile or deployment configurations accordingly.
• breaking 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.
  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.
• gotcha 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`.
  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 })`.
• gotcha 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.
  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).
• breaking 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.
  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.

Install

• npm install taskcluster-client npm
• yarn add taskcluster-client yarn
• pnpm add taskcluster-client pnpm

Imports

• taskcluster
  wrong:

  const taskcluster = require('taskcluster-client');

  correct:

  import taskcluster from 'taskcluster-client';

  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.
• QueueClient
  wrong:

  import { Queue } from 'taskcluster-client';

  correct:

  import taskcluster from 'taskcluster-client';
  const queue = new taskcluster.Queue(...);

  Client classes like `Queue` and `Auth` are accessed as properties of the `taskcluster` default export, not as named exports from the root module.
• fromEnvVars
  wrong:

  import { fromEnvVars } from 'taskcluster-client';

  correct:

  import taskcluster from 'taskcluster-client';
  const config = taskcluster.fromEnvVars();

  `fromEnvVars` is a utility function available on the `taskcluster` default export for convenient credential and root URL loading from standard Taskcluster environment variables.

Quickstart

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.

import taskcluster from 'taskcluster-client';
import { URL } from 'url';

// Load credentials from environment variables, or specify directly
const clientOptions = {
  ...taskcluster.fromEnvVars(),
  // Override rootUrl if TASKCLUSTER_PROXY_URL is desired in a task
  rootUrl: process.env.TASKCLUSTER_PROXY_URL || 'https://taskcluster.net',
  credentials: {
    clientId: process.env.TASKCLUSTER_CLIENT_ID || '',
    accessToken: process.env.TASKCLUSTER_ACCESS_TOKEN || '',
    certificate: process.env.TASKCLUSTER_CERTIFICATE ? JSON.parse(process.env.TASKCLUSTER_CERTIFICATE) : undefined
  },
  timeout: 60 * 1000, // 60-second timeout per request
  retries: 3
};

// Instantiate the Queue Client class
const queue = new taskcluster.Queue(clientOptions);

async function listTasks() {
  try {
    console.log(`Attempting to list tasks from ${clientOptions.rootUrl}...`);
    // For this example, we'll try to get the latest 10 tasks.
    // Note: 'listTasks' often requires appropriate scopes and context.
    const { tasks } = await queue.listLatestTasks({ limit: 10 });
    console.log(`Successfully retrieved ${tasks.length} tasks.`);
    for (const task of tasks) {
      console.log(`  Task ID: ${task.taskId}, State: ${task.state}`);
    }
  } catch (error) {
    console.error('Failed to list tasks:', error.message);
    if (error.statusCode === 401 || error.statusCode === 403) {
      console.error('Check your Taskcluster credentials and scopes.');
    }
  }
}

listTasks();