vercel-labs/agent-skills · error · Error

VERCEL_CLI_TOO_OLD

VERCEL_CLI_TOO_OLD

Error message

VERCEL_CLI_TOO_OLD: have ${v.join('.')}, need >= ${MIN_CLI_VERSION.join('.')}. Upgrade with `npm i -g vercel@latest`.

What it means

Thrown by checkCliVersion() after parsing the CLI version and comparing component-by-component against MIN_CLI_VERSION=[53,0,0]. The skill requires v53+ because pre-v53 lacks the `vercel metrics`, `vercel contract`, and `vercel api` subcommands the collector depends on (per the file comment). When any component is below the floor at the first differing index, the run aborts with the have/need versions.

Source

Thrown at skills/vercel-optimize/lib/vercel.mjs:107

const MIN_CLI_VERSION = [53, 0, 0];

// Pre-v53 lacks `vercel metrics` and `vercel contract`.
export async function checkCliVersion() {
  let raw;
  try {
    const { stdout } = await runVercel(['--version']);
    raw = stdout.trim();
  } catch (err) {
    throw new Error('VERCEL_NOT_INSTALLED: `vercel` CLI not found in PATH. Install with `npm i -g vercel@latest`.');
  }
  const m = raw.match(/(\d+)\.(\d+)\.(\d+)/);
  if (!m) throw new Error(`VERCEL_VERSION_UNPARSEABLE: ${raw}`);
  const v = [Number(m[1]), Number(m[2]), Number(m[3])];
  for (let i = 0; i < 3; i++) {
    if (v[i] > MIN_CLI_VERSION[i]) return v;
    if (v[i] < MIN_CLI_VERSION[i]) {
      throw new Error(
        `VERCEL_CLI_TOO_OLD: have ${v.join('.')}, need >= ${MIN_CLI_VERSION.join('.')}. Upgrade with \`npm i -g vercel@latest\`.`
      );
    }
  }
  return v;
}

export async function checkAuth() {
  try {
    await runVercel(['whoami']);
  } catch {
    throw new Error('NOT_AUTH: run `vercel login`.');
  }
}

export async function getCliIdentity() {
  const r = await runVercelJson(['whoami', '--format', 'json']);
  return r.ok ? r.data : null;

View on GitHub (pinned to b8caa260a4)

Solutions

  1. Upgrade: `npm i -g vercel@latest`, then re-run after confirming `vercel --version` reports >= 53.0.0.
  2. If a project pins an old CLI in devDependencies, bump that pin to `vercel@latest` and reinstall.
  3. Rebuild any Docker/CI image that bakes the CLI version in, so stale images stop circulating.

Example fix

// before (package.json or global install pinning an old CLI)
"vercel": "^28.0.0"

// after
"vercel": "^53.0.0"
// then: npm i -g vercel@latest  (or npm i for the devDependency)
Defensive patterns

Strategy: validation

Validate before calling

import { execFileSync } from 'node:child_process';
const MIN = [53, 0, 0];
function assertVersionOk() {
  const v = execFileSync('vercel', ['--version'], { encoding: 'utf-8' })
    .match(/(\d+)\.(\d+)\.(\d+)/).slice(1).map(Number);
  for (let i = 0; i < 3; i++) {
    if (v[i] > MIN[i]) return;
    if (v[i] < MIN[i]) throw new Error(`vercel ${v.join('.')} < ${MIN.join('.')}; upgrade`);
  }
}
assertVersionOk();

Try / catch

try {
  await checkCliVersion();
} catch (err) {
  if (err.message.startsWith('VERCEL_CLI_TOO_OLD')) {
    console.error('Upgrade the CLI and rerun: npm i -g vercel@latest');
  }
  throw err;
}

Prevention

When it happens

Trigger: An installed CLI at v52.x or earlier (lacks metrics/contract subcommands); a system with an old pinned `vercel` from a lockfile or system package manager; a Docker image baked with an older CLI.

Common situations: Long-lived CI image that ships vercel v42; a team pinning `vercel@^28` in package.json; an OS package (Homebrew/snap) lagging behind npm; local install forgotten after a machine migration.

Related errors

AI-assisted analysis of vercel-labs/agent-skills@b8caa260a4 (2026-08-13). Data as JSON: /api/errors/0b467e204e9b3480. Report an issue: GitHub.