{"record":{"id":"6c5b196d89ca6f82","repo":"can1357/oh-my-pi","slug":"unknown-capability-capabilityid","errorCode":null,"errorMessage":"Unknown capability: \"${capabilityId}\"","messagePattern":"Unknown capability: \"(.+?)\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/capability/index.ts","lineNumber":262,"sourceCode":"\t}\n\tif (options.excludeProviders) {\n\t\tconst excluded = new Set(options.excludeProviders);\n\t\tproviders = providers.filter(p => !excluded.has(p.id));\n\t}\n\n\treturn providers;\n}\n\n/**\n * Load a capability by ID.\n */\nexport async function loadCapability<T>(\n\tcapabilityId: string,\n\toptions: LoadOptions<T> = {},\n): Promise<CapabilityResult<T>> {\n\tconst capability = capabilities.get(capabilityId) as Capability<T> | undefined;\n\tif (!capability) {\n\t\tthrow new Error(`Unknown capability: \"${capabilityId}\"`);\n\t}\n\n\tconst cwd = options.cwd ?? getProjectDir();\n\tconst home = os.homedir();\n\tconst repoRoot = await findRepoRoot(cwd);\n\tconst ctx: LoadContext = { cwd, home, repoRoot };\n\tif (options.extensionRoots !== undefined) ctx.extensionRoots = options.extensionRoots;\n\tconst providers = filterProviders(capability, options);\n\n\treturn await loadImpl(capability, providers, ctx, options);\n}\n\n// =============================================================================\n// Provider Enable/Disable API\n// =============================================================================\n\n/**\n * Initialize capability system with settings manager for persistence.","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/capability/index.ts#L244-L280","documentation":"loadCapability() resolves a capability id at load time and throws if the id is not in the registry. Unlike registerProvider, it has no remediation hint — it means the caller asked to load a capability the application never defined in this process.","triggerScenarios":"Calling loadCapability(\"id\") with an id never passed to defineCapability() in the current process — typo'd id, capability module not imported, or the capability only exists in a different build/plugin set.","commonSituations":"Config or CLI references a capability by name that a disabled/missing plugin was supposed to define; stale stored settings after a capability was renamed or removed; typos in dynamically constructed ids.","solutions":["Verify the id against the exported capability constants (e.g. contextFileCapability.id) and correct it","Ensure the module defining the capability is imported before loadCapability is called","If the capability comes from config, update the stale config value to a valid capability id","List registered capabilities (e.g. iterate the registry or check exports) to see what ids exist"],"exampleFix":"// before\nawait loadCapability(\"context-files\");\n// after\nimport { contextFileCapability } from \"./capability/definitions\";\nawait loadCapability(contextFileCapability.id);","handlingStrategy":"validation","validationCode":"import { capabilities } from \".../capability\";\nif (!capabilities.has(requestedId)) {\n  throw new Error(`\"${requestedId}\" is not a registered capability; available: ${[...capabilities.keys()].join(\", \")}`);\n}\nconst result = await loadCapability(requestedId);","typeGuard":null,"tryCatchPattern":"try {\n  const result = await loadCapability(id, { cwd });\n  return result;\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unknown capability')) {\n    return { items: [], skipped: `unknown capability ${id}` };\n  }\n  throw err;\n}","preventionTips":["Reference capability ids via exported constants, never literals from config","Ensure the plugin defining the capability is loaded/enabled","Validate stored config capability names against the registry at startup","List registry keys in error surfaces to aid diagnosis"],"tags":["capability","unknown-identifier","configuration"],"backgroundTag":"capability-not-defined","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}