vercel-labs/agent-skills · error · Error

SCOPE_UNRESOLVED

SCOPE_UNRESOLVED

Error message

SCOPE_UNRESOLVED: ${commandScope.detail} Run `vercel switch <team>` or re-link with `vercel link --yes --project <project-name-or-id> --team <team-slug>`.

What it means

Thrown by main() when resolveCommandScope(project) returns {ok:false}. resolveCommandScope tries to map the project's orgId to a CLI-safe scope slug: for `team_` ids it checks whoami's currentTeam, then falls back to getTeamInfo(orgId); for `usr_` ids it derives the username from whoami. If neither path yields a usable slug (team API failed, or the linked user isn't the authed user), the command scope stays unresolved and the error embeds commandScope.detail.

Solutions

1. Switch the CLI to the right team: `vercel switch <team-slug>`, then rerun.
2. Re-link cleanly: `vercel link --yes --project <project-name-or-id> --team <team-slug>` so whoami's currentTeam matches.
3. Verify the token has access to the owning team in the Vercel dashboard and regenerate if scoped too narrowly.

Example fix

# before
$ node scripts/collect-signals.mjs
-> SCOPE_UNRESOLVED: Could not resolve the linked team ID to a CLI scope slug.

# after
$ vercel switch acme-team
$ vercel link --yes --project web --team acme-team
$ node scripts/collect-signals.mjs

const scope = await resolveCommandScope(project);
if (!scope.ok) {
  throw new Error(`Cannot resolve CLI scope: ${scope.detail}. Run 'vercel switch <team>' or re-link.`);
}
// proceed only with scope.cliScope

function isResolvedCommandScope(s) {
  return !!s && s.ok === true && typeof s.cliScope === 'string' && s.cliScope.length > 0;
}

try {
  const scope = await resolveCommandScope(project);
  if (!scope.ok) throw new Error(`SCOPE_UNRESOLVED: ${scope.detail}`);
} catch (err) {
  if (err.message.startsWith('SCOPE_UNRESOLVED')) {
    // prompt user to `vercel switch` / re-link, then retry
  }
  throw err;
}

When it happens

Trigger: The linked team id cannot be resolved via the teams API (permissions/access denied, network error); the authed user does not match the linked `usr_` id; currentTeam differs and the team lookup returned no slug.

Common situations: The CLI is logged into team A but the project belongs to team B and the user lacks access to team B; token lacks team:read scope; transient API failure during the teams lookup; user switched accounts and the link is stale.

Related errors

• NOT_AUTH
• PROJECT_SCOPE_MISMATCH
• PROJECT_SCOPE_UNRESOLVED
• RAW_ID_SCOPE_UNRESOLVED
• AMBIGUOUS_PROJECT_LINK

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

Appendix: source

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

      usage: null,
      usageScope: null,
      usageTeamTotal: null,
      usageError: 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK',
      stack,
      metrics: {},
      metricsSchema: null,
    }, { usable: true, blocker: null, detail: 'Observability Plus was not checked.' }, frameworkSupport);
    return;
  }

  if (!frameworkSupport.ok && continueUnsupportedFramework) {
    log('continuing after unsupported framework blocker because --continue-unsupported-framework was set');
  }

  log('resolving Vercel CLI command scope…');
  const commandScope = await resolveCommandScope(project);
  if (!commandScope.ok) {
    throw new Error(`SCOPE_UNRESOLVED: ${commandScope.detail} Run \`vercel switch <team>\` or re-link with \`vercel link --yes --project <project-name-or-id> --team <team-slug>\`.`);
  }
  const scope = commandScope.cliScope || undefined;
  log(`command scope resolved (source=${commandScope.source}; scoped=${scope ? 'yes' : 'no'})`);

  log('validating linked project belongs to the resolved scope…');
  const projectCfg = await getProjectConfig(project.projectId, project.orgId);
  const projectScope = validateProjectScope(projectCfg, project);
  if (!projectScope.ok) {
    throw new Error(`PROJECT_SCOPE_MISMATCH: ${projectScope.detail} Ask the user to confirm the exact Vercel project and team/personal scope, then rerun after \`vercel link --yes --project <project-name-or-id> --team <team-slug>\` or after setting both VERCEL_PROJECT_ID and VERCEL_ORG_ID for the intended scope.`);
  }
  log(`project scope verified (source=${projectScope.source})`);

  log('checking Observability Plus configuration…');
  const observabilityPlusConfig = await checkObservabilityPlusConfiguration({
    orgId: project.orgId,
    projectId: project.projectId,
  });
  log(`observabilityPlusPreflight=${observabilityPlusConfig.access === true ? 'enabled' : observabilityPlusConfig.blocker ?? 'unknown'} (${observabilityPlusConfig.source})`);

View on GitHub (pinned to b8caa260a4)