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.

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)

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
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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;
}

Prevention

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

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