angular/angular-cli · error · Error

The following packages to update are configured to use `cata

Error message

The following packages to update are configured to use `catalog:`:
${updatesList}

Because catalogs are shared across the monorepo, 'ng update' cannot modify them directly.
Please perform the following steps to update:
  1. Manually update the versions for these packages in your catalog configuration file (e.g., pnpm-workspace.yaml or .yarnrc.yml).
  2. Run '${installCmd}' to install the updated versions.
  3. Run the following command(s) from the workspace root to execute the migration schematics:
${migrationCommands}

What it means

Thrown by the update resolver when packages targeted for update are declared with `catalog:` protocol versions (pnpm catalogs / yarn catalog feature). Because catalog versions are centralized in a shared workspace file, the CLI refuses to rewrite them and instead prints the manual steps and the migration schematics commands to run afterwards.

Source

Thrown at packages/angular/cli/src/commands/update/update-resolver.ts:850

  }

  if (catalogUpdates.length > 0) {
    const packageManagerName = options.packageManager ?? 'your package manager';
    const installCmd = packageManagerName === 'yarn' ? 'yarn install' : 'pnpm install';

    const updatesList = catalogUpdates
      .map((pkg) => `  - ${pkg.name} (${pkg.specifier}) -> Target version: ${pkg.target}`)
      .join('\n');

    const migrationCommands = catalogUpdates
      .map((pkg) => {
        const fromVer = pkg.current === 'unknown' ? '<current-version>' : pkg.current;

        return `  ng update ${pkg.name} --migrate-only --from ${fromVer}`;
      })
      .join('\n');

    throw new Error(
      `The following packages to update are configured to use \`catalog:\`:\n` +
        `${updatesList}\n\n` +
        `Because catalogs are shared across the monorepo, 'ng update' cannot modify them directly.\n` +
        `Please perform the following steps to update:\n` +
        `  1. Manually update the versions for these packages in your catalog configuration file ` +
        `(e.g., pnpm-workspace.yaml or .yarnrc.yml).\n` +
        `  2. Run '${installCmd}' to install the updated versions.\n` +
        `  3. Run the following command(s) from the workspace root to execute the migration schematics:\n` +
        `${migrationCommands}`,
    );
  }
}

export async function resolveUserUpdatePlan(
  options: UpdateResolverOptions,
  packageManager: PackageManager,
  logger: logging.LoggerApi,
): Promise<UpdatePlan> {

View on GitHub (pinned to bb72145f9a)

Solutions

Manually bump the package versions in the catalog definition (pnpm-workspace.yaml or .yarnrc.yml).
Run the workspace install command (e.g. `pnpm install`) to apply new versions.
Run the printed migration commands, e.g. `ng update <pkg> --migrate-only --from <current-version>`, from the workspace root.
Alternatively, temporarily replace `catalog:` with an explicit version, run ng update, then restore the catalog reference.

Example fix

// before (pnpm-workspace.yaml)
catalog:
  '@angular/core': 17.0.0
// after
catalog:
  '@angular/core': 18.0.0
# then: pnpm install && ng update @angular/core --migrate-only --from 17.0.0

Defensive patterns

Strategy: try-catch

Validate before calling

const usesCatalog = Object.values({...pkg.dependencies, ...pkg.devDependencies})
  .some(v => v === 'catalog:');
if (usesCatalog) {
  console.warn('Packages use catalog: versions; update the catalog file manually, then run --migrate-only schematics.');
}

Try / catch

try {
  await ngUpdate(packages);
} catch (e) {
  if (e.message.includes('catalog:')) {
    // parse the listed packages from e.message, update pnpm-workspace.yaml / .yarnrc.yml,
    // run install, then run the printed `ng update <pkg> --migrate-only --from <ver>` commands
  }
}

Prevention

When adopting pnpm/yarn catalogs, plan ng update flows around manual catalog edits.
Keep catalog entries updated in the same PR as version bumps.
Document the three-step process (edit catalog, install, migrate-only schematics) for the team.
Consider temporarily pinning explicit versions when you need fully automated ng update.

When it happens

Trigger: Running `ng update` in a pnpm/yarn monorepo where one or more target packages use `catalog:` as their version range in package.json; the resolver detects catalog references in the updates list and aborts instead of editing package.json.

Common situations: Modern pnpm workspaces using pnpm-workspace.yaml catalogs; Yarn 4 catalogs configured in yarnrc.yml; teams adopting catalogs for version centralization while still using ng update.

Related errors

AI-assisted analysis of angular/angular-cli@bb72145f9a (2026-08-30). Data as JSON: /api/errors/ebb954da9abd2d41. Report an issue: GitHub.