ruvnet/ruflo · error

AIDefence failed to load

Error message

AIDefence failed to load: ${error.message}

What it means

getAIDefence() dynamically imports the optional package @claude-flow/aidefence. If the import fails with an error that is NOT 'Cannot find package' / ERR_MODULE_NOT_FOUND, the loader concludes the package IS present but broken and rethrows wrapped as 'AIDefence failed to load: <original message>'. Causes live in the embedded message: the package's own dependencies missing, an ESM/CJS or Node-version mismatch, a corrupted install, or createAIDefence returning null.

Solutions

  1. Read the text after 'AIDefence failed to load:' — it names the real cause (missing transitive dep, syntax error, ABI mismatch).
  2. Reinstall cleanly: rm -rf node_modules/@claude-flow/aidefence && npm install @claude-flow/aidefence (or a full npm ci).
  3. Align versions: install the aidefence version matching your @claude-flow/cli release instead of a floating latest.
  4. Verify with node -e "import('@claude-flow/aidefence').then(m => m.createAIDefence({enableLearning:true}))" in the same working directory.
  5. If it reproduces on a clean install, report it — the package itself is broken for your Node/platform.

Example fix

# before
npm install @claude-flow/aidefence@next   # mismatched with CLI version -> broken import

# after
npm install @claude-flow/aidefence@<version matching your @claude-flow/cli release>
node -e "import('@claude-flow/aidefence').then(m => console.log(!!m.createAIDefence({enableLearning:true})))"
Defensive patterns

Strategy: try-catch

Validate before calling

// Probe once at startup so a broken package fails loudly before work begins:
async function probeAIDefence(): Promise<boolean> {
  try {
    const m = await import('@claude-flow/aidefence');
    return typeof m.createAIDefence === 'function' && !!m.createAIDefence({ enableLearning: true });
  } catch { return false; }
}

Try / catch

try {
  return await scanForThreats(text); // AIDefence-backed tool
} catch (e) {
  if (e instanceof Error && e.message.startsWith('AIDefence failed to load:')) {
    logger.error('security scanner unavailable', { cause: e.message });
    return { degraded: true, reason: 'aidefence-broken-install' }; // fail closed & visible
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling security_tools that need AIDefence (security scan / has_pii / is_safe style tools) when @claude-flow/aidefence is installed but throws on import — e.g. its own 'Cannot find module <transitive dep>' (different message than the top-level resolution failure), an unsupported Node version, or a half-written node_modules from an interrupted install.

Common situations: Partial npm installs (killed mid-install); installing @claude-flow/aidefence at a version incompatible with the installed @claude-flow/security; native bindings inside aidefence built for a different Node ABI; running under a bundler that broke the dynamic import target.

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/bcd4d22f40ff31e8. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/cli/src/mcp-tools/security-tools.ts:69

  }

  const packageName = '@claude-flow/aidefence';

  // First attempt - try to load via dynamic import (ESM)
  try {
    const aidefence = await import(packageName);
    const instance = aidefence.createAIDefence({ enableLearning: true });
    if (!instance) {
      throw new Error('createAIDefence returned null');
    }
    aidefenceInstance = instance;
    return instance;
  } catch (e) {
    // Package not found or failed to load
    const error = e as Error;
    if (!error.message?.includes('Cannot find package') && !error.message?.includes('ERR_MODULE_NOT_FOUND')) {
      // Different error - might be a real issue
      throw new Error(`AIDefence failed to load: ${error.message}`);
    }
  }

  // Don't attempt install more than once per session
  if (installAttempted) {
    throw new Error('AIDefence package not available. Install with: npm install @claude-flow/aidefence');
  }
  installAttempted = true;

  // Second attempt - auto-install and retry
  console.error(`[claude-flow] ${packageName} not found, attempting auto-install...`);
  const installed = await autoInstallPackage(packageName);

  if (!installed) {
    throw new Error('AIDefence package not available. Install with: npm install @claude-flow/aidefence');
  }

  // #1807 — auto-install lands the package somewhere Node's standard

View on GitHub (pinned to fa13ee4ad6)