ruvnet/ruflo · error

AIDefence package not available. Install with: npm install…

Error message

AIDefence package not available. Install with: npm install @claude-flow/aidefence

What it means

The AIDefence loader auto-installs the optional @claude-flow/aidefence package at most once per process (module-level `installAttempted` flag). This variant is thrown when a load is attempted again in the same session after an earlier attempt already tried (and failed) to install — the short-circuit fires before any new install is attempted. The message tells you the durable fix is a manual install or a server restart.

Solutions

1. Install the package where the server resolves modules: npm install --save @claude-flow/aidefence in the working directory the MCP server runs from.
2. Restart the MCP server after installing — the per-session flag and module cache both reset.
3. Or run via npx ruflo@latest mcp start from a directory whose node_modules contains the package.
4. Check installability once at startup (see validation) so the first real tool call never depends on auto-install.

Example fix

# before (mid-session retry keeps failing)
> security_scan ...  # error: AIDefence package not available
> security_scan ...  # same error, installAttempted already true

# after
npm install --save @claude-flow/aidefence
# restart the MCP server, then retry the tool

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
function aidefenceResolvable(): boolean {
  try { require.resolve('@claude-flow/aidefence'); return true; } catch { return false; }
}
// At MCP server startup:
if (!aidefenceResolvable()) {
  console.error('[setup] @claude-flow/aidefence missing — run: npm install --save @claude-flow/aidefence');
  // install NOW, before any tool call, so the once-per-session auto-install budget isn't wasted
}

try {
  return await securityScan(input);
} catch (e) {
  if (e instanceof Error && e.message.includes('AIDefence package not available')) {
    disableToolCategory('aidefence'); // stop retrying this session; surface install instructions
    return { error: 'Install @claude-flow/aidefence and restart the MCP server to enable security scanning.' };
  }
  throw e;
}

When it happens

Trigger: First call to a security tool triggered auto-install which failed silently from the caller's perspective; a second call to any AIDefence-backed tool in the same MCP session then throws this immediately. Also hit when the package was installed to a location Node still can't resolve: the flag is set, so no retry occurs.

Common situations: Long-running MCP server where the first scan failed and users retry the tool; installing into the wrong directory (global CLI run from a project-less cwd); offline first attempt then network restored — the session never retries automatically.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• AIDefence installed but failed to load
• AIDefence failed to load
• Command not allowed
• Disallowed command: only npm/npx/pnpm/yarn commands are…
• Invalid argument: contains shell metacharacters

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

Appendix: source

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

    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
  // resolver couldn't find on the FIRST attempt (npm-global installs are
  // a common offender). Try Node's resolver again first (it may have
  // picked up the new node_modules directory), then fall back to the
  // file:// + cache-bust import dance, then surface a clearly actionable
  // error if everything still fails.
  // Plain re-import (covers project-local installs that landed where Node

View on GitHub (pinned to fa13ee4ad6)