Azure DevOps Node.js API Client

Common errors

• Error: TF400813: The resource cannot be found.

  cause This error typically indicates that the requested resource (e.g., a project, repository, or build definition) does not exist, or the authenticated user does not have permission to access it within the specified organization or project.
  fix Double-check the project name, repository ID, or other resource identifiers for typos. Ensure the PAT has sufficient permissions (e.g., 'Project and Team: Read', 'Code: Read'). Verify the organization URL is correct.

• Error: Failed to authenticate (401 Unauthorized)

  cause The Personal Access Token (PAT) used for authentication is either incorrect, expired, revoked, or does not have the necessary scopes to perform the requested operation.
  fix Generate a new PAT in Azure DevOps User Settings with the required scopes. Update the PAT in your application configuration. Ensure the organization URL is correct and accessible.

• TypeError: Cannot read properties of undefined (reading 'getBuilds')

  cause This error occurs when attempting to call an API method (e.g., `getBuilds`) on an API client that has not been correctly initialized or retrieved from the `WebApi` connection.
  fix Ensure you have successfully called `connection.getBuildApi()` (or similar for other APIs) and stored its result in a variable before attempting to call methods on it. Add `await` if `getBuildApi()` is an async call.

• Error: getaddrinfo ENOTFOUND dev.azure.com

  cause The Node.js environment could not resolve the hostname for the Azure DevOps organization URL. This is typically a network connectivity or DNS issue.
  fix Verify your internet connection and DNS settings. Double-check the Azure DevOps organization URL for typos. If behind a proxy, ensure Node.js is configured to use it (e.g., via `HTTPS_PROXY` environment variable).

Warnings

• breaking Major version updates (e.g., from v6.x to v15.x) frequently introduce breaking changes, primarily due to updates in the underlying Azure DevOps REST API and compatibility with specific TFS server versions. Always consult the official release notes and migration guides when upgrading.
  Fix: Review the package's GitHub releases or npm history for specific version compatibility notes. Test upgrades thoroughly in non-production environments. Pay close attention to changes in API client instantiation or method signatures.
• gotcha Authentication failures are common. Ensure your Personal Access Token (PAT) has the necessary scopes for the API calls you are making (e.g., 'Build: Read' for reading build data, 'Work Items: Read, Write' for modifying work items). PATs also have expiry dates.
  Fix: Verify the PAT's scopes in Azure DevOps User Settings -> Personal Access Tokens. Regenerate the PAT if expired or if scopes are insufficient. Test PAT validity using a simple API call.
• breaking The package maintains compatibility with specific minimum versions of TFS and Azure DevOps Server. Using a newer `azure-devops-node-api` version with an older, incompatible TFS instance will lead to runtime errors or missing functionalities. For example, `v6.6.2` supports TFS 2018 Update 2+, and earlier versions were tied to even older TFS releases.
  Fix: Check the `npm` package page or GitHub releases for explicit minimum TFS/Azure DevOps Server version compatibility for your specific client library version. Downgrade `azure-devops-node-api` if necessary to match your server's version.
• gotcha When migrating to ESM or using modern Node.js module systems, be aware of potential import issues. While `require()` generally works for older versions or CommonJS environments, `import` statements are preferred and sometimes required for newer Node.js versions and environments.
  Fix: Ensure your `tsconfig.json` (for TypeScript) or `package.json` (`"type": "module"`) is correctly configured for your chosen module system. Use `import ... from 'package';` syntax where possible. If encountering issues, try `import * as azdev from 'azure-devops-node-api';` or consult Node.js module documentation.

Install

• npm install azure-devops-node-api npm
• yarn add azure-devops-node-api yarn
• pnpm add azure-devops-node-api pnpm

Imports

• WebApi
  wrong:

  const WebApi = require('azure-devops-node-api/WebApi');

  correct:

  import { WebApi } from 'azure-devops-node-api/WebApi';

  Used to establish the connection to Azure DevOps. CommonJS `require` works but `import` is preferred in modern Node.js environments.
• getPersonalAccessTokenHandler
  wrong:

  import { PersonalAccessTokenHandler } from 'azure-devops-node-api/handlers/pat';

  correct:

  import { getPersonalAccessTokenHandler } from 'azure-devops-node-api/handlers/pat';

  This function creates an authentication handler for Personal Access Tokens (PATs), the most common authentication method. Ensure the correct named import is used.
• BuildApi
  wrong:

  import { IBuildApi } from 'azure-devops-node-api/BuildApi';

  correct:

  import { BuildApi } from 'azure-devops-node-api/BuildApi';

  Specific API clients like `BuildApi`, `GitApi`, `CoreApi`, etc., are imported directly from their respective paths. Do not import the interface (`IBuildApi`) directly for instantiation.
• * as azdev
  wrong:

  const azdev = require('azure-devops-node-api').default;

  correct:

  import * as azdev from 'azure-devops-node-api';

  A common pattern for importing all public exports from the main entry point, useful for accessing various utilities and the `WebApi` class without individual path imports.

Quickstart

This quickstart demonstrates how to authenticate with Azure DevOps using a Personal Access Token (PAT), establish a connection, obtain a `BuildApi` client, and list the most recent builds for a specified project.

import { WebApi } from 'azure-devops-node-api/WebApi';
import { getPersonalAccessTokenHandler } from 'azure-devops-node-api/handlers/pat';
import { BuildApi } from 'azure-devops-node-api/BuildApi';

async function listBuilds() {
  const orgUrl = process.env.AZURE_DEVOPS_ORG_URL ?? 'https://dev.azure.com/your-organization';
  const token = process.env.AZURE_DEVOPS_PAT ?? ''; // Ensure PAT has 'Build: Read' scope
  const projectName = process.env.AZURE_DEVOPS_PROJECT_NAME ?? 'MyProject';

  if (!token) {
    console.error('AZURE_DEVOPS_PAT environment variable is not set.');
    return;
  }

  try {
    const authHandler = getPersonalAccessTokenHandler(token);
    const connection = new WebApi(orgUrl, authHandler);
    
    // Get the Build API client
    const buildApi: BuildApi = await connection.getBuildApi();

    // List recent builds for a specific project
    console.log(`Fetching builds for project: ${projectName}...`);
    const builds = await buildApi.getBuilds(projectName, undefined, undefined, undefined, undefined, undefined, 5); // Get top 5 builds

    if (builds.length === 0) {
      console.log('No builds found.');
      return;
    }

    console.log(`Found ${builds.length} recent builds:`)
    for (const build of builds) {
      console.log(`  - Build #${build.buildNumber}: ${build.status} - ${build.result ?? 'N/A'}`);
    }
  } catch (error: any) {
    console.error('Error fetching builds:', error.message);
    if (error.statusCode === 401) {
      console.error('Check your PAT and organization URL. Ensure PAT has sufficient scopes.');
    } else if (error.statusCode === 404) {
      console.error('Project or organization URL not found.');
    }
  }
}

listBuilds();