vercel-labs/agent-skills · critical · Error

VERCEL_NOT_INSTALLED

VERCEL_NOT_INSTALLED

Error message

VERCEL_NOT_INSTALLED: `vercel` CLI not found in PATH. Install with `npm i -g vercel@latest`.

What it means

Thrown by checkCliVersion() when `runVercel(['--version'])` rejects. runVercel shells out to the `vercel` executable resolved by command.file, so a rejection means no `vercel` binary is on PATH (ENOENT) or exec itself failed. The skill hard-requires the CLI because every signal comes from `vercel metrics`/`usage`/`contract`/`api`, so absence is a hard stop, not a degraded path.

Source

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

  const command = resolveVercelCommand({ env: opts.env });
  if (command.missing) {
    const err = new Error('VERCEL_NOT_INSTALLED: `vercel` CLI not found in PATH. Install with `npm i -g vercel@latest`.');
    err.code = 'ENOENT';
    throw err;
  }
  return await exec(command.file, [...command.prefix, ...args], { windowsHide: true, ...opts });
}

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']);

View on GitHub (pinned to b8caa260a4)

Solutions

1. Run `npm i -g vercel@latest` (or `pnpm`/`yarn` global equivalent) and confirm with `vercel --version`.
2. Verify the binary is resolvable: `command -v vercel` returns a path on the same PATH the Node process inherits.
3. If you cannot install globally, run the script through a wrapper that puts the npx cache bin on PATH, or pin `vercel` as a devDependency and invoke via `node_modules/.bin/vercel`.
4. In CI, add an explicit `npm i -g vercel@latest` step before the collect-signals job.

Example fix

// before
await checkCliVersion(); // throws VERCEL_NOT_INSTALLED on a clean machine

// after — gate the call so you fail with an actionable message before the skill runs
import { execFileSync } from 'node:child_process';
try { execFileSync('vercel', ['--version'], { stdio: 'ignore' }); }
catch { throw new Error('Install Vercel CLI first: npm i -g vercel@latest'); }
await checkCliVersion();

import { execFileSync } from 'node:child_process';
// Run before checkCliVersion()
function assertVercelInstalled() {
  try { execFileSync('vercel', ['--version'], { stdio: 'pipe' }); }
  catch (e) { throw new Error('Vercel CLI not on PATH. Install: npm i -g vercel@latest'); }
}
assertVercelInstalled();

try {
  await checkCliVersion();
} catch (err) {
  if (err.message.startsWith('VERCEL_NOT_INSTALLED')) {
    // actionable: instruct install, do not retry in-process
    throw new Error('Install Vercel CLI first, then rerun: npm i -g vercel@latest');
  }
  throw err;
}

When it happens

Trigger: Any call to checkCliVersion() (the first step of collect-signals.mjs main()) on a machine where `vercel` is not installed, not on PATH, or the resolved command.file shim points to a missing binary. Also fires if the global install is corrupt and `vercel --version` exits non-zero before printing anything.

Common situations: Fresh CI runner or container without the Vercel CLI installed; a local npx-only workflow where `vercel` was never installed globally; PATH shadowed by a different `vercel` shim; Node installed via a version manager that resets PATH so the globally-installed CLI drops out.

Related errors

• VERCEL_VERSION_UNPARSEABLE
• VERCEL_CLI_TOO_OLD
• NOT_AUTH
• RAW_ID_SCOPE_UNRESOLVED
• UNKNOWN_ARG

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