vercel-labs/agent-skills · error · Error

RAW_ID_SCOPE_UNRESOLVED

RAW_ID_SCOPE_UNRESOLVED

Error message

RAW_ID_SCOPE_UNRESOLVED: resolve the linked org/user ID to a CLI scope slug before running Vercel commands.

What it means

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.

Source

Thrown at skills/vercel-optimize/lib/vercel.mjs:847

    try {
      const content = await readFile(join(cwd, name), 'utf-8');
      if (/\bcacheComponents\s*:\s*true\b/.test(content)) return true;
      if (/\bcacheComponents\s*:\s*false\b/.test(content)) return false;
    } catch {}
  }
  return null;
}

async function pathExists(p) {
  try { await access(p); return true; } catch { return false; }
}

// `--scope <teamId>` is buggy on several subcommands (silently falls back to
// currentTeam). Resolve raw account IDs to slugs/usernames before scoped calls.
function scopedArgs(args, scope) {
  if (!scope) return args;
  if (typeof scope === 'string' && /^(team|usr)_/.test(scope)) {
    throw new Error('RAW_ID_SCOPE_UNRESOLVED: resolve the linked org/user ID to a CLI scope slug before running Vercel commands.');
  }
  return [...args, '--scope', scope];
}

// CLI summary field is `<metric_id_with_underscores>_<aggregation>` (e.g. `vercel_request_count_sum`).
export function normalizeSummary(metricResponse, metricId, aggregation, groupBy = []) {
  if (!metricResponse || metricResponse.error) return [];
  const field = `${metricId.replace(/\./g, '_')}_${aggregation}`;
  const rows = Array.isArray(metricResponse.summary) ? metricResponse.summary : [];
  return rows.map((row) => {
    const out = { value: row[field] ?? null };
    for (const dim of groupBy) {
      if (row[dim] !== undefined) out[dim] = row[dim];
    }
    return out;
  });
}

View on GitHub (pinned to b8caa260a4)

Solutions

1. 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.
2. If you are constructing scopedArgs manually, pass the team slug or username, never the `team_`/`usr_` id.
3. Ensure the prior resolveCommandScope step succeeded (check .ok) before reaching scoped commands.

Example fix

// before — passing raw orgId straight to a scoped command
scopedArgs(['metrics'], project.orgId); // project.orgId === 'team_abc' -> throws

// after — resolve to a slug first
const scope = await resolveCommandScope(project);
if (!scope.ok) throw new Error('cannot resolve scope');
scopedArgs(['metrics'], scope.cliScope); // cliScope is the slug

function assertScopeIsSlug(scope) {
  if (typeof scope === 'string' && /^(team|usr)_/.test(scope)) {
    throw new Error(`scope '${scope}' is a raw id; resolve to a slug/username via resolveCommandScope first`);
  }
}
// before any scopedArgs call:
assertScopeIsSlug(scope);

function isResolvedScopeSlug(scope) {
  return typeof scope === 'string' && scope.length > 0 && !/^(team|usr)_/.test(scope);
}

let args;
try {
  args = scopedArgs(baseArgs, scope);
} catch (err) {
  if (err.message.startsWith('RAW_ID_SCOPE_UNRESOLVED')) {
    const resolved = await resolveCommandScope(project);
    if (!resolved.ok) throw err;
    args = scopedArgs(baseArgs, resolved.cliScope); // retry with slug
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• VERCEL_NOT_INSTALLED
• VERCEL_VERSION_UNPARSEABLE
• VERCEL_CLI_TOO_OLD
• NOT_AUTH
• UNKNOWN_ARG

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