Turborepo

Common errors

• Error: Failed to authenticate with Vercel for remote caching.

  cause Vercel authentication token is expired, invalid, or permissions are insufficient, or the authentication flow has changed.
  fix Run `npx turbo login` to re-authenticate or verify `TURBO_TOKEN` in CI/CD. Refer to documentation for the latest authentication procedures (especially for versions >=2.9.7).

• Error: Failed to parse pnpm-lock.yaml: unknown format version

  cause Using pnpm v11 multi-document lockfiles with Turborepo versions prior to 2.9.7.
  fix Upgrade Turborepo to v2.9.7 or newer to ensure full compatibility with pnpm v11 lockfiles.

• Error: Task 'build' did not exit cleanly

  cause Turborepo process or its child processes did not terminate gracefully, potentially leading to hanging processes or incorrect exit codes in CI/CD environments.
  fix Upgrade Turborepo to v2.9.7 or newer to benefit from improved graceful shutdown handling.

Warnings

• breaking Turborepo v2.9.7 introduces a transition to standard OAuth/device flows for Vercel authentication. This is a breaking change for existing setups relying on legacy token methods for remote caching, including CI/CD.
  Fix: Update your CI/CD configurations and re-authenticate using the new OAuth/device flows. Consult the Turborepo (v2.9.7+) documentation for details.
• gotcha Even with recent fixes, users might encounter transient issues with Vercel authentication token persistence across login flows or after updates. This can lead to unexpected remote cache misses.
  Fix: If remote caching fails unexpectedly, try re-running `npx turbo login` to refresh your authentication tokens. Ensure Vercel environment variables are correctly set in CI/CD.

Install

• npm install turbo npm
• yarn add turbo yarn
• pnpm add turbo pnpm

Quickstart

This demonstrates how to initialize a new Turborepo monorepo, install dependencies, and run a development script across all workspaces.

npx create-turbo@latest my-monorepo
cd my-monorepo
pnpm install
npx turbo dev