vercel/next.js · error

Failed to link project ${linkRes.stdout} ${linkRes.stderr} (

Error message

Failed to link project ${linkRes.stdout} ${linkRes.stderr} (${linkRes.exitCode})

What it means

Thrown by deployProject in the Vercel benchmark harness when `vercel link -p <project> --confirm` exits with a non-zero code. The link step associates the local app folder with an existing Vercel project under the test team scope; failure here blocks deployment. The message includes the command's stdout, stderr, and exit code.

Source

Thrown at bench/vercel/project-utils.js:143

}

export async function deployProject(projectName, appFolder) {
  try {
    const vercelFlags = ['--scope', TEST_TEAM_NAME]
    const vercelEnv = { ...process.env, TOKEN: TEST_TOKEN }

    // link the project
    const linkRes = await execa(
      'vercel',
      ['link', '-p', projectName, '--confirm', ...vercelFlags],
      {
        cwd: appFolder,
        env: vercelEnv,
      }
    )

    if (linkRes.exitCode !== 0) {
      throw new Error(
        `Failed to link project ${linkRes.stdout} ${linkRes.stderr} (${linkRes.exitCode})`
      )
    }

    const deployRes = await execa(
      'vercel',
      [
        'deploy',
        '--build-env',
        'NEXT_PRIVATE_TEST_MODE=1',
        '--build-env',
        'NEXT_TELEMETRY_DISABLED=1',
        ...(VERCEL_EDGE_FUNCTIONS_BRIDGE_PKG
          ? [
              '--build-env',
              `VERCEL_EDGE_FUNCTIONS_BRIDGE_PKG=${VERCEL_EDGE_FUNCTIONS_BRIDGE_PKG}`,
            ]
          : []),

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Read the included stderr — it usually states auth failure, project not found, or scope error.
2. Verify TEST_TOKEN is valid and not expired; rotate it if needed.
3. Confirm TEST_TEAM_NAME matches a team the token can access and that the project exists there.
4. Ensure the vercel CLI is installed and the folder is not already linked (run `vercel unlink` or remove the .vercel/ folder).

Example fix

# before: stale token
TOKEN=expired ...

# after: rotate token in Vercel dashboard, set fresh secret
vercel whoami --token $TEST_TOKEN  # confirm works

// Verify auth + project existence before linking
import execa from 'execa'
async function preflight(token: string, scope: string, project: string) {
  const who = await execa('vercel', ['whoami', '--token', token])
  if (who.exitCode !== 0) throw new Error('TEST_TOKEN invalid or expired')
  const ls = await execa('vercel', ['ls', '--scope', scope, '--token', token])
  if (!ls.stdout.includes(project)) throw new Error(`Project ${project} not found in ${scope}`)
}

null

try {
  await deployProject(name, folder)
} catch (e) {
  // message includes stdout/stderr/exitCode from vercel link
  console.error('Link failed — check token/scope/project:', (e as Error).message)
  throw e
}

When it happens

Trigger: The project name does not exist in the team; the TEST_TOKEN is invalid/expired; the TEST_TEAM_NAME scope is wrong or the token lacks access; network/CLI error; vercel CLI not installed or wrong version; the local folder is already linked to a different project.

Common situations: Expired test token in CI secrets; the benchmark project was deleted from the team; scope mismatch; vercel CLI version drift changes link flags.

Related errors

• Failed to deploy project ${linkRes.stdout} ${linkRes.stderr}
• Unknown option: --${rawKey}
• Invalid --top value: ${topRaw}
• Invalid numeric value for --${key}: ${value}
• --routes cannot be empty

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/23e477fcc50db06d. Report an issue: GitHub.