vercel-labs/skills · warning · WellKnownScopeNotFoundError

WellKnownScopeNotFoundError(scope.scopePath, scope.rootBaseU

Error message

WellKnownScopeNotFoundError(scope.scopePath, scope.rootBaseUrl)

What it means

WellKnownProvider.fetchAllSkills throws WellKnownScopeNotFoundError when a scoped search (e.g. 'skills add python/pandas-tutorial') narrowed the candidate list to a scope but produced zero matching skills — i.e. the scope path exists in the registry but contains no (non-internal) skill for your query. It is re-thrown verbatim rather than swallowed like other provider errors.

Source

Thrown at src/providers/wellknown.ts:629

    try {
      const candidates = await this.fetchIndexCandidates(url);
      const scope = this.getScope(url);
      const scopedCandidates = scope
        ? candidates.filter((c) => c.resolvedBaseUrl !== scope.rootBaseUrl)
        : candidates;
      const includeInternal = options.includeInternal || shouldInstallInternalSkills();

      for (const result of scopedCandidates) {
        const skillPromises = result.entries.map((entry) => this.fetchSkillByEntry(entry));
        const results = await Promise.all(skillPromises);
        const skills = results
          .filter((s: WellKnownSkill | null): s is WellKnownSkill => s !== null)
          .filter((skill) => includeInternal || skill.metadata?.internal !== true);
        if (skills.length > 0) return skills;
      }

      if (scope && scopedCandidates.length < candidates.length) {
        throw new WellKnownScopeNotFoundError(scope.scopePath, scope.rootBaseUrl);
      }

      return [];
    } catch (error) {
      if (error instanceof WellKnownScopeNotFoundError) throw error;
      return [];
    }
  }

  private computeDigest(bytes: Uint8Array): string {
    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
  }

  private extractArchive(
    bytes: Uint8Array,
    artifactUrl: string,
    contentType: string
  ): Map<string, WellKnownFileContent> {

View on GitHub (pinned to 435076e789)

Solutions

Re-run the search without the scope restriction to list what is actually available: skills find <query>
Check exact skill names with the registry's listing/CLI list command; fix typos
Upgrade the skills CLI in case the well-known registry index format changed
If all skills in the scope are internal, request a public variant or different scope

Example fix

# before
skills add python/pandas-tutorail   # typo inside valid scope
# after
skills add python/pandas-tutorial

Defensive patterns

Strategy: try-catch

Validate before calling

const skills = await provider.listSkills(scope); // cheap listing first
const match = skills.find((s) => s.name === wantedName);
if (!match) throw new Error(`Skill '${wantedName}' not found in scope '${scope}'; available: ${skills.map((s) => s.name).join(', ')}`);

Type guard

function isScopeNotFound(e: unknown): e is Error {
  return e instanceof Error && e.constructor.name === 'WellKnownScopeNotFoundError';
}

Try / catch

try { await fetchAllSkills(query); }
catch (e) {
  if (isScopeNotFound(e)) {
    return fetchAllSkills(query.replace(/^\S+\//, '')); // retry without scope
  }
  throw e;
}

Prevention

List available skills in a scope before requesting a specific one
Validate typed user input against known skill names before search
Handle WellKnownScopeNotFoundError separately — it is re-thrown, unlike other provider errors

When it happens

Trigger: Searching a well-known registry with an explicit scope where scope.scopePath matched, scopedCandidates is a strict subset of candidates, and every candidate failed to fetch or was filtered out (internal-only). Zero unscoped results are then not tolerated, so the scope-not-found error surfaces.

Common situations: Typos in the skill name within a valid scope ('owner/repo@skill' where skill doesn't exist); scopes whose skills are all marked internal; registry index drift after a version change; offline fetches where all candidates failed network-wise inside a scope.

Related errors

AI-assisted analysis of vercel-labs/skills@435076e789 (2026-08-28). Data as JSON: /api/errors/d301563fa72bf5d8. Report an issue: GitHub.