What causes "Unknown capability: "${capabilityId}"" in can1357/oh-my-pi?

Verify the id against the exported capability constants (e.g. contextFileCapability.id) and correct it

can1357/oh-my-pi · error · Error

Unknown capability: "${capabilityId}"

Error message

Unknown capability: "${capabilityId}"

What it means

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.

Source

Thrown at packages/coding-agent/src/capability/index.ts:262

	}
	if (options.excludeProviders) {
		const excluded = new Set(options.excludeProviders);
		providers = providers.filter(p => !excluded.has(p.id));
	}

	return providers;
}

/**
 * Load a capability by ID.
 */
export async function loadCapability<T>(
	capabilityId: string,
	options: LoadOptions<T> = {},
): Promise<CapabilityResult<T>> {
	const capability = capabilities.get(capabilityId) as Capability<T> | undefined;
	if (!capability) {
		throw new Error(`Unknown capability: "${capabilityId}"`);
	}

	const cwd = options.cwd ?? getProjectDir();
	const home = os.homedir();
	const repoRoot = await findRepoRoot(cwd);
	const ctx: LoadContext = { cwd, home, repoRoot };
	if (options.extensionRoots !== undefined) ctx.extensionRoots = options.extensionRoots;
	const providers = filterProviders(capability, options);

	return await loadImpl(capability, providers, ctx, options);
}

// =============================================================================
// Provider Enable/Disable API
// =============================================================================

/**
 * Initialize capability system with settings manager for persistence.

View on GitHub (pinned to 9690622007)

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

Example fix

// before
await loadCapability("context-files");
// after
import { contextFileCapability } from "./capability/definitions";
await loadCapability(contextFileCapability.id);

Defensive patterns

Strategy: validation

Validate before calling

import { capabilities } from ".../capability";
if (!capabilities.has(requestedId)) {
  throw new Error(`"${requestedId}" is not a registered capability; available: ${[...capabilities.keys()].join(", ")}`);
}
const result = await loadCapability(requestedId);

Try / catch

try {
  const result = await loadCapability(id, { cwd });
  return result;
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unknown capability')) {
    return { items: [], skipped: `unknown capability ${id}` };
  }
  throw err;
}

Prevention

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

When it happens

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

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

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/6c5b196d89ca6f82. Report an issue: GitHub.