{"record":{"id":"4bf54e403df677e6","repo":"ruvnet/ruflo","slug":"aidefence-installed-but-failed-to-load-retryerr","errorCode":null,"errorMessage":"AIDefence installed but failed to load: ${retryError}.\nThis usually means npm installed the package somewhere Node's module resolver doesn't search (common with global installs of `claude-flow`). Recovery options:\n  1. Run `npm install --save @claude-flow/aidefence` in your project's working directory.\n  2. Or run `npx ruflo@latest mcp start` from a directory whose node_modules contains the package.\n  3. Or restart the MCP server after the install completes.","messagePattern":"AIDefence installed but failed to load: (.+?)\\.\nThis usually means npm installed the package somewhere Node's module resolver doesn't search \\(common with global installs of `claude-flow`\\)\\. Recovery options:\n  1\\. Run `npm install --save @claude-flow/aidefence` in your project's working directory\\.\n  2\\. Or run `npx ruflo@latest mcp start` from a directory whose node_modules contains the package\\.\n  3\\. Or restart the MCP server after the install completes\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/mcp-tools/security-tools.ts","lineNumber":120,"sourceCode":"      return instance;\n    }\n  } catch { /* fall through to file:// attempt */ }\n\n  // file:// + cache-bust attempt (covers globally-installed packages whose\n  // path the standard resolver missed but require.resolve can locate).\n  try {\n    const modulePath = require.resolve(packageName);\n    const cacheBust = `?t=${Date.now()}`;\n    const aidefence = await import(`file://${modulePath}${cacheBust}`);\n    const instance = aidefence.createAIDefence({ enableLearning: true });\n    if (!instance) {\n      throw new Error('createAIDefence returned null after install');\n    }\n    aidefenceInstance = instance;\n    console.error(`[claude-flow] ${packageName} loaded after install (file:// path)`);\n    return instance;\n  } catch (retryError) {\n    throw new Error(\n      `AIDefence installed but failed to load: ${retryError}.\\n` +\n      `This usually means npm installed the package somewhere Node's module resolver doesn't search ` +\n      `(common with global installs of \\`claude-flow\\`). Recovery options:\\n` +\n      `  1. Run \\`npm install --save @claude-flow/aidefence\\` in your project's working directory.\\n` +\n      `  2. Or run \\`npx ruflo@latest mcp start\\` from a directory whose node_modules contains the package.\\n` +\n      `  3. Or restart the MCP server after the install completes.`\n    );\n  }\n}\n\n/**\n * Scan input for AI manipulation threats\n */\nconst aidefenceScanTool: MCPTool = {\n  name: 'aidefence_scan',\n  description: 'Scan input text for AI manipulation threats (prompt injection, jailbreaks, PII). Returns threat assessment with <10ms latency. Use when nothing native exists — Claude Code does not have a PII / prompt-injection / adversarial-text scanner. Pair with any tool that ingests untrusted input (browser scrape, federation envelope, memory_import_claude).',\n  inputSchema: {\n    type: 'object',","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/mcp-tools/security-tools.ts#L102-L138","documentation":"The final failure of the AIDefence loader: auto-install reported success, but both the plain re-import AND the require.resolve + `file://<path>?t=<ts>` cache-bust import still threw. This almost always means npm placed the package somewhere Node's resolver doesn't search relative to the CLI (classic with global installs of claude-flow), so the module exists on disk but is unresolvable. The error embeds the retry error plus three recovery options.","triggerScenarios":"Globally installed `claude-flow` auto-installs @claude-flow/aidefence into a prefix (e.g. ~/.npm-global or the npx cache) that is not in the resolution path of the running MCP server; then even the file:// retry fails because require.resolve from the CLI's location can't find it, or the cache-bust import hits a sub-dependency resolution failure.","commonSituations":"npx/global installs where cwd has no node_modules; running the MCP server from a different directory than where installation happened; ESM resolver quirks with query-string cache busting on some Node versions.","solutions":["Follow option 1: npm install --save @claude-flow/aidefence in your project's working directory, then restart the MCP server.","Option 2: run npx ruflo@latest mcp start from a directory whose node_modules contains the package.","Option 3: simply restart the MCP server after the install completed — the fresh module cache often resolves the newly installed tree.","For global installs, prefer making the package a real project dependency so npm's resolution rules work in your favor."],"exampleFix":"# before\ncd ~ && claude-flow mcp start   # global install, aidefence unresolvable -> error 289\n\n# after\ncd ~/my-project && npm install --save @claude-flow/aidefence && npx ruflo@latest mcp start","handlingStrategy":"fallback","validationCode":"import { createRequire } from 'node:module';\nconst require = createRequire(import.meta.url);\nfunction aidefenceResolvableAfterInstall(): boolean {\n  try { require.resolve('@claude-flow/aidefence'); return true; }\n  catch {\n    console.error('Recovery: cd <project> && npm install --save @claude-flow/aidefence, then restart the MCP server');\n    return false;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await securityScan(text);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('AIDefence installed but failed to load')) {\n    notifyOps('aidefence unresolvable from this install layout — restart MCP server from a project dir containing the package');\n    return { degraded: true, reason: 'aidefence-module-layout' };\n  }\n  throw e;\n}","preventionTips":["Run the MCP server with cwd = the project whose node_modules holds @claude-flow/aidefence.","Prefer project-local installs over global claude-flow installs when using AIDefence features.","After any install of the package, restart the MCP server so the ESM cache re-resolves cleanly."],"tags":["security","aidefence","module-resolution","npm","global-install"],"backgroundTag":"module-resolution-failed","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}