{"record":{"id":"ef6bb1d4856af1d0","repo":"vercel-labs/agent-skills","slug":"raw-id-scope-unresolved","errorCode":"RAW_ID_SCOPE_UNRESOLVED","errorMessage":"RAW_ID_SCOPE_UNRESOLVED: resolve the linked org/user ID to a CLI scope slug before running Vercel commands.","messagePattern":"RAW_ID_SCOPE_UNRESOLVED: resolve the linked org/user ID to a CLI scope slug before running Vercel commands\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"skills/vercel-optimize/lib/vercel.mjs","lineNumber":847,"sourceCode":"    try {\n      const content = await readFile(join(cwd, name), 'utf-8');\n      if (/\\bcacheComponents\\s*:\\s*true\\b/.test(content)) return true;\n      if (/\\bcacheComponents\\s*:\\s*false\\b/.test(content)) return false;\n    } catch {}\n  }\n  return null;\n}\n\nasync function pathExists(p) {\n  try { await access(p); return true; } catch { return false; }\n}\n\n// `--scope <teamId>` is buggy on several subcommands (silently falls back to\n// currentTeam). Resolve raw account IDs to slugs/usernames before scoped calls.\nfunction scopedArgs(args, scope) {\n  if (!scope) return args;\n  if (typeof scope === 'string' && /^(team|usr)_/.test(scope)) {\n    throw new Error('RAW_ID_SCOPE_UNRESOLVED: resolve the linked org/user ID to a CLI scope slug before running Vercel commands.');\n  }\n  return [...args, '--scope', scope];\n}\n\n// CLI summary field is `<metric_id_with_underscores>_<aggregation>` (e.g. `vercel_request_count_sum`).\nexport function normalizeSummary(metricResponse, metricId, aggregation, groupBy = []) {\n  if (!metricResponse || metricResponse.error) return [];\n  const field = `${metricId.replace(/\\./g, '_')}_${aggregation}`;\n  const rows = Array.isArray(metricResponse.summary) ? metricResponse.summary : [];\n  return rows.map((row) => {\n    const out = { value: row[field] ?? null };\n    for (const dim of groupBy) {\n      if (row[dim] !== undefined) out[dim] = row[dim];\n    }\n    return out;\n  });\n}\n","sourceCodeStart":829,"sourceCodeEnd":865,"githubUrl":"https://github.com/vercel-labs/agent-skills/blob/b8caa260a420a73042e35521de4b5c8baf6446cc/skills/vercel-optimize/lib/vercel.mjs#L829-L865","documentation":"Thrown by scopedArgs() when the `scope` argument is a raw account id matching /^(team|usr)_/. The code comment explains `--scope <teamId>` is buggy on several CLI subcommands (silently falls back to currentTeam), so the skill deliberately refuses to pass raw IDs and requires a resolved slug/username instead. This is a defensive guard, not a runtime failure of Vercel — it prevents silently querying the wrong account.","triggerScenarios":"Calling any internal helper that routes through scopedArgs with an unresolved `team_…` or `usr_…` id; resolveCommandScope returned a slug but a code path passed the raw orgId directly; env/config supplied a raw id where a slug was expected.","commonSituations":"A caller reads `.vercel/repo.json` orgId (a raw `team_` id) and hands it straight to a scoped command; a custom script bypasses resolveCommandScope; the team API lookup that would have converted id→slug failed upstream and a raw id leaked through.","solutions":["Resolve the raw id to a slug before any scoped call: use resolveCommandScope(project) which calls getTeamInfo()/whoami to map team_/usr_ ids to slugs.","If you are constructing scopedArgs manually, pass the team slug or username, never the `team_`/`usr_` id.","Ensure the prior resolveCommandScope step succeeded (check .ok) before reaching scoped commands."],"exampleFix":"// before — passing raw orgId straight to a scoped command\nscopedArgs(['metrics'], project.orgId); // project.orgId === 'team_abc' -> throws\n\n// after — resolve to a slug first\nconst scope = await resolveCommandScope(project);\nif (!scope.ok) throw new Error('cannot resolve scope');\nscopedArgs(['metrics'], scope.cliScope); // cliScope is the slug","handlingStrategy":"validation","validationCode":"function assertScopeIsSlug(scope) {\n  if (typeof scope === 'string' && /^(team|usr)_/.test(scope)) {\n    throw new Error(`scope '${scope}' is a raw id; resolve to a slug/username via resolveCommandScope first`);\n  }\n}\n// before any scopedArgs call:\nassertScopeIsSlug(scope);","typeGuard":"function isResolvedScopeSlug(scope) {\n  return typeof scope === 'string' && scope.length > 0 && !/^(team|usr)_/.test(scope);\n}","tryCatchPattern":"let args;\ntry {\n  args = scopedArgs(baseArgs, scope);\n} catch (err) {\n  if (err.message.startsWith('RAW_ID_SCOPE_UNRESOLVED')) {\n    const resolved = await resolveCommandScope(project);\n    if (!resolved.ok) throw err;\n    args = scopedArgs(baseArgs, resolved.cliScope); // retry with slug\n  } else throw err;\n}","preventionTips":["Always route scoped commands through resolveCommandScope; never pass orgId directly.","Check resolveCommandScope().ok before issuing scoped calls.","Treat any `team_`/`usr_` prefixed string as unresolved until mapped to a slug."],"tags":["scope","cli","defensive-guard","vercel"],"backgroundTag":null,"analyzedSha":"b8caa260a420a73042e35521de4b5c8baf6446cc","analyzedAt":"2026-08-13T06:03:29.508Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}