ruvbot does not export createAIDefenceGuard. Ensure ruvbot@0

Error message

ruvbot does not export createAIDefenceGuard. Ensure ruvbot@0.1.8 or later is installed.

What it means

After the ruvbot module imports successfully, the integration looks up mod.createAIDefenceGuard and requires it to be a function before building the guard. An installed-but-old ruvbot (pre-0.1.8) or a different package occupying the 'ruvbot' name lacks that export, so this distinct 'wrong version' error fires even though the package resolved fine. The guard initialization promise is cached, so a failed init retries on next use.

Source

Thrown at v3/@claude-flow/guidance/src/ruvbot-integration.ts:248

    };
  }

  /**
   * Lazily initialize the underlying ruvbot AIDefence guard.
   * Safe to call multiple times; only the first call creates the guard.
   */
  private async ensureGuard(): Promise<RuvBotAIDefenceGuard> {
    if (this.guard) return this.guard;

    if (!this.guardInitPromise) {
      this.guardInitPromise = (async () => {
        const mod = await requireRuvBot();
        const createGuard = mod['createAIDefenceGuard'] as
          | ((config?: Record<string, unknown>) => RuvBotAIDefenceGuard)
          | undefined;

        if (typeof createGuard !== 'function') {
          throw new Error(
            'ruvbot does not export createAIDefenceGuard. ' +
            'Ensure ruvbot@0.1.8 or later is installed.',
          );
        }

        this.guard = createGuard({
          detectPromptInjection: this.config.detectPromptInjection,
          detectJailbreak: this.config.detectJailbreak,
          detectPII: this.config.detectPII,
        });
      })();
    }

    await this.guardInitPromise;
    return this.guard!;
  }

  /**

View on GitHub (pinned to fa13ee4ad6)

Solutions

Upgrade to a compatible release: npm install ruvbot@^0.1.8 (or latest)
Verify the export exists in the installed version: node -e "import('ruvbot').then(m => console.log(typeof m.createAIDefenceGuard))" — should print 'function'
Pin ruvbot in package.json so lockfile drift cannot resurrect an old version
If the export is genuinely absent in your fork, disable the AIDefenceGate integration instead of retrying

Example fix

# before
npm ls ruvbot # ruvbot@0.1.1 — no createAIDefenceGuard export
# after
npm install ruvbot@0.1.8
node -e "import('ruvbot').then(m => console.log(typeof m.createAIDefenceGuard))" # function

Defensive patterns

Strategy: type-guard

Validate before calling

const mod = (await import('ruvbot')) as Record<string, unknown>;
if (typeof mod['createAIDefenceGuard'] !== 'function') {
  throw new Error('Installed ruvbot is too old; run: npm install ruvbot@0.1.8');
}
const guard = (mod['createAIDefenceGuard'] as () => RuvBotAIDefenceGuard)();

Type guard

function exportsCreateAIDefenceGuard(mod: Record<string, unknown>): boolean {
  return typeof mod['createAIDefenceGuard'] === 'function';
}

Try / catch

try {
  const gate = new AIDefenceGate({});
} catch (err) {
  if (err instanceof Error && err.message.includes('does not export createAIDefenceGuard')) {
    throw new Error('ruvbot version mismatch: upgrade with npm install ruvbot@0.1.8');
  }
  throw err;
}

Prevention

Pin ruvbot@^0.1.8 in package.json so lockfiles cannot keep a pre-export version
Verify typeof (await import('ruvbot')).createAIDefenceGuard === 'function' in smoke tests
Beware same-named packages on private registries shadowing npm's ruvbot

When it happens

Trigger: A stale ruvbot from an old lockfile (version < 0.1.8) resolving correctly but exporting no createAIDefenceGuard; a same-named private/forked package installed in its place; partial upgrades where ruvbot was pinned years ago.

Common situations: Lockfiles keeping ancient optional deps; corporate registries serving a different 'ruvbot'; upgrading @claude-flow/guidance without re-checking its peer version requirements.

Related errors

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