vercel-labs/agent-skills · critical · Error

NO_PROJECT_ID

NO_PROJECT_ID

Error message

NO_PROJECT_ID: pass one as argv, set VERCEL_PROJECT_ID, or run `vercel link` in this directory.

What it means

Thrown by main() in collect-signals.mjs when resolveProjectId(explicit) returns null — meaning no positional projectId was given, VERCEL_PROJECT_ID env is unset, and neither `.vercel/repo.json` nor `.vercel/project.json` yielded a projectId. The skill intentionally does not auto-run `vercel link` (the code comment says interactive surprises are bad), so it surfaces this error and asks the user to link explicitly.

Source

Thrown at skills/vercel-optimize/scripts/collect-signals.mjs:72

  return { explicitProjectId, continueWithoutObservability, continueUnsupportedFramework };
}

async function main() {
  const { explicitProjectId, continueWithoutObservability, continueUnsupportedFramework } = parseArgs(process.argv.slice(2));

  log('checking Vercel CLI version…');
  const cli = await checkCliVersion();
  log(`vercel CLI v${cli.join('.')} OK`);

  log('checking auth…');
  await checkAuth();
  log('auth OK');

  log('resolving project id…');
  const project = await resolveProjectId(explicitProjectId);
  if (!project) {
    throw new Error(
      'NO_PROJECT_ID: pass one as argv, set VERCEL_PROJECT_ID, or run `vercel link` in this directory.'
    );
  }
  log(`project link resolved (source=${project.source}; teamScope=${project.orgId ? 'yes' : 'no'})`);

  if (!project.orgId) {
    throw new Error('PROJECT_SCOPE_UNRESOLVED: the project was resolved without an owner account. Ask the user which Vercel team or personal scope owns the project, then rerun from a linked app directory or set VERCEL_PROJECT_ID with VERCEL_ORG_ID for that scope.');
  }

  log('checking framework support…');
  const stack = await detectStack();
  const frameworkSupport = classifyFrameworkSupport(stack);
  log(`framework=${stack.framework}@${stack.frameworkVersion ?? '?'} support=${frameworkSupport.status}`);

  if (!frameworkSupport.ok && !continueUnsupportedFramework) {
    writeOutput({
      schemaVersion: SCHEMA_VERSION,
      collectedAt: new Date().toISOString(),

View on GitHub (pinned to b8caa260a4)

Solutions

Run `vercel link` in the project directory to create `.vercel/repo.json` (or `.vercel/project.json`).
Pass the projectId as the first positional: `node scripts/collect-signals.mjs prj_xxx`.
Set VERCEL_PROJECT_ID (and VERCEL_ORG_ID for scope) in the environment.

Example fix

# before
$ node scripts/collect-signals.mjs
-> NO_PROJECT_ID: pass one as argv, set VERCEL_PROJECT_ID, or run `vercel link`.

# after
$ vercel link
# or
$ VERCEL_PROJECT_ID=prj_xxx VERCEL_ORG_ID=team_yyy node scripts/collect-signals.mjs

Defensive patterns

Strategy: validation

Validate before calling

import { readFile } from 'node:fs/promises';
import { exists } from 'node:fs/promises';
async function assertProjectResolvable(cwd = process.cwd()) {
  if (process.env.VERCEL_PROJECT_ID) return;
  if (await exists(`${cwd}/.vercel/repo.json`) || await exists(`${cwd}/.vercel/project.json`)) return;
  throw new Error('No projectId: run `vercel link`, pass projectId, or set VERCEL_PROJECT_ID');
}
await assertProjectResolvable();

Try / catch

let project;
try {
  project = await resolveProjectId(explicit);
} catch (e) { throw e; }
if (!project) {
  // prompt user to link, then rerun
  throw new Error('Link the project first: vercel link');
}

Prevention

Run `vercel link` once per project directory as part of setup.
In CI, set VERCEL_PROJECT_ID (+ VERCEL_ORG_ID) instead of relying on link files.
Commit or persist `.vercel` link files in CI artifacts when reusing workspaces.

When it happens

Trigger: Running collect-signals in a directory that was never `vercel link`ed, with no projectId arg and no VERCEL_PROJECT_ID env; the `.vercel` directory is gitignored/absent in CI; project.json/repo.json present but missing the id/projectId fields.

Common situations: Fresh clone in CI without linking step; running from the wrong directory; `.vercel` stripped from the artifact; a detached working copy.

Related errors

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