ruvnet/ruflo · warning

Dependencies not available

Error message

Dependencies not available

What it means

ReasoningBank.initialize() dynamically imports the AgentDB adapter and HNSW index modules; when either fails to load it throws 'Dependencies not available'. Importantly, the surrounding catch swallows this throw and downgrades the bank to in-memory-only mode (useRealBackend = false), so in practice this error signals degraded capability — no vector persistence — rather than a crash. You mostly observe it via logs and the missing real backend.

Source

Thrown at v3/@claude-flow/hooks/src/reasoningbank/index.ts:265

        });

        await this.agentDB.initialize();
        this.useRealBackend = true;

        // Try to use real embedding service
        if (EmbeddingServiceImpl && !this.config.useMockEmbeddings) {
          try {
            this.embeddingService = new RealEmbeddingService(this.config.dimensions);
            await (this.embeddingService as RealEmbeddingService).initialize();
          } catch (e) {
            console.warn('[ReasoningBank] Real embeddings unavailable, using hash-based fallback');
          }
        }

        await this.loadPatterns();
        console.log(`[ReasoningBank] Initialized with AgentDB + HNSW (M=${this.config.hnswM}, efConstruction=${this.config.hnswEfConstruction})`);
      } else {
        throw new Error('Dependencies not available');
      }

      this.initialized = true;
      this.emit('initialized', {
        shortTermCount: this.shortTermPatterns.size,
        longTermCount: this.longTermPatterns.size,
        useRealBackend: this.useRealBackend,
      });
    } catch (error) {
      // Fallback to in-memory only mode
      console.warn('[ReasoningBank] AgentDB not available, using in-memory mode');
      this.useRealBackend = false;
      this.initialized = true;
    }
  }

  /**
   * Load optional dependencies

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Install the optional/native dependencies the adapter loads (@claude-flow/memory and its HNSW bindings) in the target environment
2. After initialize(), check the 'initialized' event's useRealBackend flag and fail loudly in environments that require persistence
3. If in-memory operation is acceptable for that deployment, treat the console warning as expected and document it

Example fix

// before
const bank = new ReasoningBank();
await bank.initialize(); // native deps missing -> silently degrades to in-memory

// after
const bank = new ReasoningBank();
bank.on('initialized', (info) => {
  if (!info.useRealBackend && process.env.REQUIRE_VECTOR_BACKEND === '1') {
    throw new Error('ReasoningBank fell back to in-memory mode; install @claude-flow/memory native deps');
  }
});
await bank.initialize();

// Detect the degraded mode explicitly instead of relying on the swallowed throw
const bank = new ReasoningBank();
bank.on('initialized', (info: { useRealBackend: boolean }) => {
  if (!info.useRealBackend && process.env.REQUIRE_VECTOR_BACKEND === '1') {
    throw new Error('ReasoningBank is in-memory only; native AgentDB/HNSW deps did not load');
  }
});
await bank.initialize();

// initialize() already catches internally; wrap to observe capability only
try {
  await bank.initialize();
} finally {
  const real = /* from the 'initialized' event payload */ useRealBackend;
  if (!real) logger.warn('ReasoningBank degraded: in-memory mode (no vector persistence)');
}

When it happens

Trigger: Calling await bank.initialize() in an environment where the @claude-flow/memory native/optional dependencies (AgentDB bindings, HNSW/ruvector NAPI modules) are not installed, not built for the platform, or excluded by the bundler's handling of the webpackIgnore'd dynamic import.

Common situations: Optional dependencies skipped during npm install --omit=optional or prune; native modules compiled for a different Node ABI or OS (deploying to Alpine/containers); bundlers statically resolving and dropping the dynamic import; CI passing with in-memory mode unnoticed while production silently loses persistence.

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

• Embedding service not initialized
• native keychain backend unavailable
• ruflo auth needs the '@claude-flow/security' package, which
• "@agntcy/slim-bindings" is installed but does not export pub
• "@agntcy/slim-bindings" is installed but does not export joi

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