{"record":{"id":"d301563fa72bf5d8","repo":"vercel-labs/skills","slug":"wellknownscopenotfounderror-scope-scopepath-scope","errorCode":null,"errorMessage":"WellKnownScopeNotFoundError(scope.scopePath, scope.rootBaseUrl)","messagePattern":"WellKnownScopeNotFoundError\\(scope\\.scopePath, scope\\.rootBaseUrl\\)","errorType":"exception","errorClass":"WellKnownScopeNotFoundError","httpStatus":null,"severity":"warning","filePath":"src/providers/wellknown.ts","lineNumber":629,"sourceCode":"    try {\n      const candidates = await this.fetchIndexCandidates(url);\n      const scope = this.getScope(url);\n      const scopedCandidates = scope\n        ? candidates.filter((c) => c.resolvedBaseUrl !== scope.rootBaseUrl)\n        : candidates;\n      const includeInternal = options.includeInternal || shouldInstallInternalSkills();\n\n      for (const result of scopedCandidates) {\n        const skillPromises = result.entries.map((entry) => this.fetchSkillByEntry(entry));\n        const results = await Promise.all(skillPromises);\n        const skills = results\n          .filter((s: WellKnownSkill | null): s is WellKnownSkill => s !== null)\n          .filter((skill) => includeInternal || skill.metadata?.internal !== true);\n        if (skills.length > 0) return skills;\n      }\n\n      if (scope && scopedCandidates.length < candidates.length) {\n        throw new WellKnownScopeNotFoundError(scope.scopePath, scope.rootBaseUrl);\n      }\n\n      return [];\n    } catch (error) {\n      if (error instanceof WellKnownScopeNotFoundError) throw error;\n      return [];\n    }\n  }\n\n  private computeDigest(bytes: Uint8Array): string {\n    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;\n  }\n\n  private extractArchive(\n    bytes: Uint8Array,\n    artifactUrl: string,\n    contentType: string\n  ): Map<string, WellKnownFileContent> {","sourceCodeStart":611,"sourceCodeEnd":647,"githubUrl":"https://github.com/vercel-labs/skills/blob/435076e78988e1e6ec40d00b0b1d76bdbbc5419a/src/providers/wellknown.ts#L611-L647","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nskills add python/pandas-tutorail   # typo inside valid scope\n# after\nskills add python/pandas-tutorial","handlingStrategy":"try-catch","validationCode":"const skills = await provider.listSkills(scope); // cheap listing first\nconst match = skills.find((s) => s.name === wantedName);\nif (!match) throw new Error(`Skill '${wantedName}' not found in scope '${scope}'; available: ${skills.map((s) => s.name).join(', ')}`);","typeGuard":"function isScopeNotFound(e: unknown): e is Error {\n  return e instanceof Error && e.constructor.name === 'WellKnownScopeNotFoundError';\n}","tryCatchPattern":"try { await fetchAllSkills(query); }\ncatch (e) {\n  if (isScopeNotFound(e)) {\n    return fetchAllSkills(query.replace(/^\\S+\\//, '')); // retry without scope\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["registry","search","scope","wellknown-provider"],"backgroundTag":"resource-not-found-in-scope","analyzedSha":"435076e78988e1e6ec40d00b0b1d76bdbbc5419a","analyzedAt":"2026-08-28T17:47:53.369Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}