What causes "SONA learning failed: ${error}" in ruvnet/ruflo?

Read the text after 'SONA learning failed:' — it names the real failure; fix that first

SONA learning failed: ${error}

Error message

SONA learning failed: ${error}

What it means

SONALearningEngine.learn() wraps its entire body — engine.beginTrajectory(), per-step context recording, endTrajectory(id, quality) and flush() — in a try/catch that rethrows everything as 'SONA learning failed: <original error>'. The prefix is generic; the actual cause is the wrapped text, most often trajectory-lifecycle misuse of the underlying SONA engine (already-ended or unknown trajectory id, uninitialized or shut-down engine) or a failure inside the active mode's learn step during flush().

Source

Thrown at v3/@claude-flow/neural/src/sona-integration.ts:199

          step.reward
        );
      }

      // Set context if available
      if (trajectory.domain) {
        this.engine.addTrajectoryContext(trajectoryId, trajectory.domain);
      }

      // Complete trajectory with quality score
      const quality = this.calculateQuality(trajectory);
      this.engine.endTrajectory(trajectoryId, quality);

      // Flush instant updates
      this.engine.flush();

      this.learningTimeMs = performance.now() - startTime;
    } catch (error) {
      throw new Error(`SONA learning failed: ${error}`);
    }
  }

  /**
   * Adapt behavior based on context
   *
   * @param context - Current context for adaptation
   * @returns Adapted behavior with transformed embeddings
   */
  async adapt(context: Context): Promise<AdaptedBehavior> {
    const startTime = performance.now();

    try {
      // Apply micro-LoRA transformation
      const transformedQuery = this.engine.applyMicroLora(
        Array.from(context.queryEmbedding)
      );

View on GitHub (pinned to fa13ee4ad6)

Solutions

Read the text after 'SONA learning failed:' — it names the real failure; fix that first
Do not learn() the same trajectory twice — track learned ids in a Set
Ensure initialize() has resolved and cleanup() is not running concurrently
Once the underlying cause is fixed, retry with a fresh engine/trajectory if the error was transient (I/O, timing)

Example fix

// before
await engine.learn(trajectory); // 'SONA learning failed: ...' - cause buried

// after
try {
  await engine.learn(trajectory);
} catch (e) {
  const cause = (e as Error).message.replace(/^SONA learning failed: /, '');
  logger.error('learn failed', { cause });
  throw e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

const learned = new Set<string>();
async function learnOnce(engine: SONALearningEngine, trajectory: Trajectory) {
  if (learned.has(trajectory.trajectoryId)) return; // avoid double-learn
  await engine.learn(trajectory);
  learned.add(trajectory.trajectoryId);
}

Try / catch

try {
  await engine.learn(trajectory);
} catch (e) {
  const cause = (e as Error).message.replace(/^SONA learning failed: /, '');
  // 'cause' is the real error (e.g. trajectory already ended, engine not initialized)
  logger.error('SONA learn failed', { cause });
  // classify: lifecycle misuse -> permanent, do not retry; transient -> rebuild and retry once
}

Prevention

Initialize the engine before learning and never clean up mid-flight
Track already-learned trajectory ids to prevent double learn()
Log the unwrapped cause, not just the 'SONA learning failed' prefix
Fix the underlying cause before retrying - a blind retry of the same trajectory repeats the failure

When it happens

Trigger: Calling learn() twice with the same trajectory so begin/endTrajectory hit an already-ended id; learn() before initialize() finished or after cleanup() started; flush() throwing because the active SONA mode (balanced/research/edge/batch/real-time) failed its internal learn step; malformed trajectories (missing steps or domain) tripping engine internals.

Common situations: Retrying a failed learn() with the same trajectory object; shutting the neural system down while learning is in flight; mode-specific bugs that only surface in research or edge modes.

Related errors

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