paperclipai/paperclip · error · Error

bundled plugin auto-install key "${key}" is not in the bundl

Error message

bundled plugin auto-install key "${key}" is not in the bundled catalog (known keys: ${known}); refusing to start

What it means

Catalog guard in resolveBundledPluginInstalls: an auto-install key (from bundled plugin config) has no matching entry in BUNDLED_PLUGIN_CATALOG. The message lists all known keys; startup refuses rather than silently skipping a requested plugin.

Source

Thrown at server/src/services/bundled-plugins.ts:170

 */
export function resolveBundledPluginInstalls(
  keys: readonly string[],
  opts: {
    catalogRoot: string;
    env: Record<string, string | undefined>;
    enforceCatalogRoot: boolean;
  },
): ResolvedBundledPlugin[] {
  const resolved: ResolvedBundledPlugin[] = [];
  const seen = new Set<string>();
  const canonicalRoot = canonicalize(opts.catalogRoot);
  for (const key of keys) {
    if (seen.has(key)) continue;
    seen.add(key);
    const entry = BUNDLED_PLUGIN_CATALOG.find((candidate) => candidate.key === key);
    if (!entry) {
      const known = BUNDLED_PLUGIN_CATALOG.map((candidate) => candidate.key).join(", ");
      throw new Error(
        `bundled plugin auto-install key "${key}" is not in the bundled catalog (known keys: ${known}); refusing to start`,
      );
    }
    const override = entry.pathOverrideEnvVar
      ? opts.env[entry.pathOverrideEnvVar]?.trim()
      : undefined;
    const localPath = override
      ? path.resolve(override)
      : path.resolve(opts.catalogRoot, entry.relativePath);
    if (opts.enforceCatalogRoot && !isInsideRoot(canonicalize(localPath), canonicalRoot)) {
      throw new Error(
        `bundled plugin "${key}" resolves to "${localPath}", outside the bundled catalog root "${opts.catalogRoot}"; refusing to start`,
      );
    }
    resolved.push({ key: entry.key, pluginKey: entry.pluginKey, localPath });
  }
  return resolved;
}

View on GitHub (pinned to 01ad858492)

Solutions

1. Use one of the known bundled catalog keys listed in the message for auto-install.
2. Remove the unknown key from the auto-install configuration.

When it happens

Trigger: Thrown at server/src/services/bundled-plugins.ts:170 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/eb26bb1fa36b4cf3. Report an issue: GitHub.