ruvnet/ruflo · error · Error

SONA not initialized. Call initializeTraining with useSona:

Error message

SONA not initialized. Call initializeTraining with useSona: true

What it means

Thrown by sonaForceLearn() (and its sibling sonaFindPatterns/sonaTick) when the SONA engine is null. initializeTraining() attempts SONA by default (config.useSona !== false), but on import failure of the optional @ruvector/sona package it silently sets sonaAvailable=false and leaves sonaEngine null — only warning when you explicitly passed useSona: true. So despite the message's advice, the usual cause is not a missing flag but a missing/unresolvable @ruvector/sona install (or cleanup() having flushed and nulled the engine).

Source

Thrown at v3/@claude-flow/cli/src/services/ruvector-training.ts:716

// ============================================

/**
 * Check if SONA is available
 */
export function isSonaAvailable(): boolean {
  return sonaAvailable && sonaEngine !== null;
}

/**
 * Force-learn a pattern with SONA (1.6μs, 624k ops/s)
 * This is a one-shot learning mechanism for immediate pattern storage
 */
export function sonaForceLearn(
  embedding: Float32Array,
  reward: number
): void {
  if (!sonaEngine) {
    throw new Error('SONA not initialized. Call initializeTraining with useSona: true');
  }

  sonaEngine.forceLearn(embedding, reward);
  totalSonaLearns++;
}

/**
 * Search for similar patterns with SONA (16.7μs, 60k searches/s)
 * Returns the k most similar patterns from the pattern bank
 */
export function sonaFindPatterns(
  embedding: Float32Array,
  k: number = 5
): unknown[] {
  if (!sonaEngine) {
    throw new Error('SONA not initialized. Call initializeTraining with useSona: true');
  }

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Check readiness with the exported isSonaAvailable() before any SONA call — it reflects whether the engine actually constructed.
2. If false, verify @ruvector/sona is present and resolvable: npm ls @ruvector/sona; reinstall without --omit=optional; for bundlers, mark it external or ensure it's in node_modules at runtime.
3. Call initializeTraining() (SONA is attempted by default — no flag needed once the package resolves); pass { useSona: true } so import failures at least log a warning instead of failing silently.
4. After cleanup(), re-run initializeTraining() before further one-shot learning.

Example fix

// before
await initializeTraining(); // @ruvector/sona failed to import, silently skipped
sonaForceLearn(embedding, reward); // throws 'SONA not initialized…'

// after
const init = await initializeTraining({ useSona: true }); // logs a warning if import fails
if (!isSonaAvailable()) {
  throw new Error(`SONA unavailable in this install — features: ${init.features.join(', ')}`);
}
sonaForceLearn(embedding, reward);

import { initializeTraining, isSonaAvailable, sonaForceLearn } from './services/ruvector-training.js';

const init = await initializeTraining({ useSona: true }); // explicit flag ⇒ import failures at least log a warning
if (!isSonaAvailable()) {
  throw new Error(`SONA unavailable — install @ruvector/sona. Features: ${init.features.join(', ')}`);
}
sonaForceLearn(embedding, reward);

import { isSonaAvailable } from './services/ruvector-training.js';

// built-in readiness predicate (not a type narrow, but the module's official check):
function assertSonaReady(): void {
  if (!isSonaAvailable()) {
    throw new Error('SONA engine absent — initializeTraining could not import @ruvector/sona');
  }
}

try {
  sonaForceLearn(embedding, reward);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('SONA not initialized')) {
    if (!isSonaAvailable()) {
      // engine genuinely absent: skip one-shot learning, don't crash the caller
      return;
    }
    await initializeTraining(); // was torn down by cleanup(): re-init and retry
    sonaForceLearn(embedding, reward);
    return;
  }
  throw e;
}

When it happens

Trigger: Calling sonaForceLearn after an init where the '@ruvector/sona' dynamic import threw (not installed, pruned optionalDependency, unresolvable specifier in the bundler); initializing with { useSona: false } and still calling SONA functions; calling after cleanup() (which flushes and nulls sonaEngine).

Common situations: Bundlers (esbuild/webpack) that can't resolve the optional CJS/ESM interop target so importWithInterop fails at runtime; slim container images; version skew where @ruvector/sona's SonaEngine export moved; tests that cleanup() between suites but keep calling one-shot learn.

Related errors

• Flash attention not initialized
• MoE attention not initialized
• Hyperbolic attention not initialized
• Contrastive loss not initialized
• Optimizer not initialized

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