{"record":{"id":"385262e8cbd6a4d7","repo":"vercel-labs/agent-skills","slug":"scope-unresolved","errorCode":"SCOPE_UNRESOLVED","errorMessage":"SCOPE_UNRESOLVED: ${commandScope.detail} Run `vercel switch <team>` or re-link with `vercel link --yes --project <project-name-or-id> --team <team-slug>`.","messagePattern":"SCOPE_UNRESOLVED: (.+?) Run `vercel switch <team>` or re-link with `vercel link --yes --project <project-name-or-id> --team <team-slug>`\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"skills/vercel-optimize/scripts/collect-signals.mjs","lineNumber":128,"sourceCode":"      usage: null,\n      usageScope: null,\n      usageTeamTotal: null,\n      usageError: 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK',\n      stack,\n      metrics: {},\n      metricsSchema: null,\n    }, { usable: true, blocker: null, detail: 'Observability Plus was not checked.' }, frameworkSupport);\n    return;\n  }\n\n  if (!frameworkSupport.ok && continueUnsupportedFramework) {\n    log('continuing after unsupported framework blocker because --continue-unsupported-framework was set');\n  }\n\n  log('resolving Vercel CLI command scope…');\n  const commandScope = await resolveCommandScope(project);\n  if (!commandScope.ok) {\n    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>\\`.`);\n  }\n  const scope = commandScope.cliScope || undefined;\n  log(`command scope resolved (source=${commandScope.source}; scoped=${scope ? 'yes' : 'no'})`);\n\n  log('validating linked project belongs to the resolved scope…');\n  const projectCfg = await getProjectConfig(project.projectId, project.orgId);\n  const projectScope = validateProjectScope(projectCfg, project);\n  if (!projectScope.ok) {\n    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.`);\n  }\n  log(`project scope verified (source=${projectScope.source})`);\n\n  log('checking Observability Plus configuration…');\n  const observabilityPlusConfig = await checkObservabilityPlusConfiguration({\n    orgId: project.orgId,\n    projectId: project.projectId,\n  });\n  log(`observabilityPlusPreflight=${observabilityPlusConfig.access === true ? 'enabled' : observabilityPlusConfig.blocker ?? 'unknown'} (${observabilityPlusConfig.source})`);","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/vercel-labs/agent-skills/blob/b8caa260a420a73042e35521de4b5c8baf6446cc/skills/vercel-optimize/scripts/collect-signals.mjs#L110-L146","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Switch the CLI to the right team: `vercel switch <team-slug>`, then rerun.","Re-link cleanly: `vercel link --yes --project <project-name-or-id> --team <team-slug>` so whoami's currentTeam matches.","Verify the token has access to the owning team in the Vercel dashboard and regenerate if scoped too narrowly."],"exampleFix":"# before\n$ node scripts/collect-signals.mjs\n-> SCOPE_UNRESOLVED: Could not resolve the linked team ID to a CLI scope slug.\n\n# after\n$ vercel switch acme-team\n$ vercel link --yes --project web --team acme-team\n$ node scripts/collect-signals.mjs","handlingStrategy":"validation","validationCode":"const scope = await resolveCommandScope(project);\nif (!scope.ok) {\n  throw new Error(`Cannot resolve CLI scope: ${scope.detail}. Run 'vercel switch <team>' or re-link.`);\n}\n// proceed only with scope.cliScope","typeGuard":"function isResolvedCommandScope(s) {\n  return !!s && s.ok === true && typeof s.cliScope === 'string' && s.cliScope.length > 0;\n}","tryCatchPattern":"try {\n  const scope = await resolveCommandScope(project);\n  if (!scope.ok) throw new Error(`SCOPE_UNRESOLVED: ${scope.detail}`);\n} catch (err) {\n  if (err.message.startsWith('SCOPE_UNRESOLVED')) {\n    // prompt user to `vercel switch` / re-link, then retry\n  }\n  throw err;\n}","preventionTips":["Ensure the authed user has access to the owning team before running.","Use `vercel switch <team>` so whoami's currentTeam matches the project owner.","Grant the token team:read scope so getTeamInfo can resolve the slug."],"tags":["scope","auth","team","vercel"],"backgroundTag":null,"analyzedSha":"b8caa260a420a73042e35521de4b5c8baf6446cc","analyzedAt":"2026-08-13T06:03:29.508Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}